,

API Series: Authentication

Security is a big deal with anything on the web, and APIs are no exception. Many times an API provider requires authentication to verify the caller has permissions to make a request and usually some type of access key is required. The Znode API follows this same convention and makes it easy to authenticate requests to its endpoints.

Like many other APIs, the Znode API uses basic authentication with the Authorization header to validate requests. An example of the format for the Authorization header is as follows:

Authorization: Basic d3d3Lm15LXN0b3JlLmNvbXw1RDJCNEM1RS1EOEIzLTQ0ODgtOTA0RC02NDA5NDc2MkUxMzY=

The value you see after the word “Basic” is a Base64 encoded string that consists of a username and password separated by a pipe character (username|password), as described below:

Username This is the domain name for the store whose data will be retrieved during the request (i.e. www.my-store.com).
Password This is the API key for the domain, as found in the ZNodeDomain table in the Multifront database (i.e. 5D2B4C5E-D8B3-4488-904D-64094762E136).

Any client of the Znode API must concatenate the domain name (username ) with the domain key (password), separated by a pipe, and then Base64 encode that string to pass along in the Authorization header.

When a request is made to an endpoint, the Znode API will look for the Authorization header and try to decode it. It will then split the decoded string into the domain name (username) and domain key (password), verify that they are a match, then process the request.

If the Authorization header isn’t in the request or if either the domain name (username) or domain key (password) are empty, the API request will fail with the following information:

HTTP status code 403 Forbidden
HTTP status description Domain name and key are either incorrect or missing from the request Authorization header.

Disabling Authentication

Authentication can be disabled by setting ValidateAuthHeader to false in the <appSettings> section of the API’s web.config file. However, in most cases, this value should be set to true in production environments.

<add key="ValidateAuthHeader" value="true" />

During Development

When developing a client that uses the Znode API, it will be useful at times to open endpoints in a browser in order to see data. To ensure this is possible, you need to add an entry in the ZNodeDomain table for the domain of the API itself. In this case, simply disabling authentication will have no effect.

For example, if you have the API deployed locally at “api.localhost.com”, you should add an entry in the ZNodeDomain table where the DomainName field is “api.localhost.com” with the relevant portal ID. This will be the context for retrieving data when viewing endpoints in a browser.

IMPORTANT: This should be for development purposes only.

HTTPS and SSL

The requirement to run under HTTPS is specific to your requirements and infrastructure; therefore, the Znode API doesn’t force you to use HTTPS to run it. However, we strongly recommend it, especially for production environments. During development, it would be beneficial to create and install a local SSL certificate in order to properly mimic all calls to the Znode API.