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:
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:
This is the domain name for the store whose data will be retrieved during the request (i.e. www.my-store.com).
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
HTTP status description
Domain name and key are either incorrect or missing from the request Authorization header.
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" />
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.