aluma.io

The Aluma Developer Hub

Welcome to the Aluma developer hub. You'll find comprehensive guides and documentation to help you start working with Aluma as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

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:

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 6 months ago

Authenticating API requests


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.