Authentication

The API supports 2 authentication mechanisms: Basic and API-key-based.

Basic authentication requires that a valid username and password is base64 encoded into the headers for each request.

ApiKey authentication requires an initial call to the API using Basic authentication to acquire a valid API key. This key can then be included in all request headers without the need to store user credentials.

When an ApiKey has been acquired, all requests made using that key will be under the account of the user who made the original request for the key.

Step 1: Request an API Key

Note: you should only need to request an API key once per application; NOT for every request.

To request a key you need to POST to /api/auth specifying a name parameter to describe the requested key. You can also optionally specify a lifetime for the key. For the sample we will only create a 1 minute API key to avoid polluting the environment with sample keys.

request({
    method: 'POST',
    url: config.siteUrl + '/api/auth?name=ApiSamples&lifetime=00:01:00',
    auth: {
        user: username,
        pass: password
    },
    json:true
});

Step 2: Use the API key

Once you have created an API key you can use it to authenticate for all future requests.

Set the value against the X-ApiKey header and your request will be treated as if it had come from the same user that requested the key.

See the Entities page for an example call.

Samples

• API Key Authentication