Authenticating API requests

Every use of the API requires authentication so that we can ensure that only authorised users and systems can interact with the API.

All requests are authenticated using OAuth2 access tokens.

In order to make requests to the API you need a valid access token that will then be sent with each request. An access token is a data string that enables Waives to verify that a request belongs to an authorised account.

To get an access token and use it to authenticate an API request you should:

1. Create an API Client in the dashboard
2. Take note of the Client ID and Client Secret for the API Client
3. Call the token endpoint https://api.aluma.io/oauth/token with the Client ID and Client Secret to get an access token
4. Include the access token in the Authorization header of every request to the API

To exchange a Client ID and Client Secret for an access token, send an application/x-www-form-urlencoded request, as follows:

You will receive a response like this:

{
  "access_token": "<MY_ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 86400
}

The access_token property is your access token. The expires_in property specifies the number of seconds in which this access token will expire. You should make a request for a new access token at this point, or a little before.

With every request to the API you should then specify the Authorization header as follows:

Authorization: Bearer <MY_ACCESS_TOKEN>

If you forget to do this, or your access token has expired, you will receive a 401 Unauthorized response.

🚧

Expiring access tokens

Access tokens expire (currently after 24 hours), after which you will need to generate a new token. If you continue to use an expired token you will receive a 401 Unauthorized response. You should check the response from the token endpoint for the expiry time for the token rather than hard-coding it as the token lifetime may be changed in the future.