Authentication and Security

You need an API key and token to access data with the API.

API Key - Application

An API key identifies the application interacting with the API. So in order to get started with the API, the first thing you want to do is create an API key.

API Token - User

An API token identifies the user on behalf of which the application is interacting with the API. The application can exchange user credentials (e-mail address and password) for a token using the authentication resource. Tokens expire after 24 hours if they're not used.

Using API Keys and Tokens

Some REST resources only require an API key but most (those that access your data) require either

  • an API key authorized to access data in a group; or
  • an API key and an API token for a user that has the correct permissions in the group.

The general rule is: If your application is acting on behalf of a user it should include an API token (identifying the user) in the request. On the other hand, if your application is not acting on behalf of a user (which would be the case for example when syncing data between two systems), it should only include its API key.

Keys and tokens can be sent either with HTTP headers API-Key and API-Token: 

API-Key: my-api-key
API-Token: my-users-api-token

Or, they can be sent as query parameters api_key and api_token: 

/the/resource?api_key=my-api-key&api_token=my-users-api-token

Signing requests

By using request signing you can prevent unauthorized access to your data. When using signatures, an attacker cannot simply sniff up your API key and use it to access your data, but the attacker would also need to know the signing secret.

Because we want it to be simple to get started with the API, request signatures are not required by default. However, we highly recommend enabling this requirement on your API keys once the integration goes into production. Don't re-use an API key that you've used for testing and previously did not have this requirement.

The signature is passed using either the API-Signature header or the signature query parameter.

In addition to the signature, you must pass a timestamp for the request, so that the signed data (method and URL) is not identical for repeated requests. The timestamp is passed using either the API-Signature-Timestamp header or the signature_timestamp query parameter.

The signature is a Base64 encoded HMAC-SHA1 hash using (as signature base) the HTTP method, timestamp and URI string excluding the signature and signature_timestamp query parameters and value (if they're used). The method, timstamp and URI are concatenated with an underscore (_) as separator.

For example, to list the first 5 customers, we would GET the resource /customer?limit=5. If we use a millisecond timestamp of 1395357126997, the signature base would then be: 

GET_1395357126997_/customer?limit=5

Thus the request with signature headers would be: 

GET https://app.coredination.net/api/1/customer?limit=5
API-Key: 007fa82b-93f0-4a06-81f6-339dcaad126f
API-Signature-Timestamp: 1395357126997
API-Signature: 9HJMAsC3+M8CgdBAAieSs9VZmUE=

or query parameters: 

GET https://app.coredination.net/api/1/customer?limit=5&api_key=007fa82b-93f0-4a06-81f6-339dcaad126f&signature_timestamp=1395357126997&signature=IHdgUVy4krvm%2FaNlvSWsY94RH20%3D

Note that the signatures in the two examples above are different, since the query parameter version also includes the api_key=... parameter in the signing data. Also note that the signature as a query parameter needs to be URL encoded.

You can use the following code example to generate the signature: