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:
- Create an API Client in the dashboard
- Take note of the Client ID and Client Secret for the API Client
- Call the token endpoint
https://api.aluma.io/oauth/token
with the Client ID and Client Secret to get an access token - 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:
Parameter | Type | Description |
---|---|---|
client_id | String | The Client ID of the API Client requesting authentication. To get the Client ID for your API Client, view your API clients in the dashboard, and find the item labelled "Id". The text of that item is the client ID. |
client_secret | String | The Client Secret of the API Client requesting authentication. To get the Client Secret for your API Client, view your API clients in the dashboard, and find the item labelled "Secret". The text of that item is the Client Secret. |
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.
Updated about 3 years ago