Skip to main content
Authentication takes place in two steps. In the first, the API key is exchanged for an access token. In the second, the token is presented in each request to the protected operations.

​
API key

The API key is composed of a public identifier and a secret. The secret is displayed only once, when the key is generated, and cannot be retrieved afterwards. The key identifies the holding account, so that every authenticated operation is restricted to the data of that account.

​
Token issuance

The POST /auth operation issues the access token. The request uses the HTTP Basic authentication scheme (RFC 7617): the public identifier takes the position of the username, and the secret, that of the password.
Invalid credentials result in a 401 response.

​
Token use

The token is presented in the Authorization header, under the Bearer scheme (RFC 6750).
A missing, invalid or expired token, or a blocked holding account, results in a 401 response. A resource belonging to another account is treated as nonexistent and results in a 404 response.

​
Lifetime and renewal

The token is valid for one minute. There is no renewal operation: once the lifetime has elapsed, a new token must be issued through POST /auth. It is recommended that the integration keep the token in memory, track the expiry time from expiresIn and request a new token ahead of expiry, rather than waiting for a 401 response.
The API key and the access token must not be embedded in applications running on the end user’s device or in source code repositories. Requests must originate exclusively from servers under the integrator’s control.