Introduction

APSIS One API uses Bearer Authentication as designed in RFC 6750. This guide will teach you how to authenticate your integration with our API.

Create an API key

Create an API key in your APSIS One account settings. You can have multiple API keys to better manage your integrations with APSIS One API. Once you've deleted an API key in APSIS One account settings, APSIS One API will no longer accept it.

Add the API key to your integration settings

Store client ID and secret key in your integration settings. These are in fact the credentials to APSIS One API and thus it's sensitive data so it's best to encrypt them at rest and in transfer.

Obtain an access token

Call our token endpoint providing your client ID and secret key in the request body:

curl --location --request POST 'https://api.apsis.one/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "client_credentials",
  "client_id": "b49b39a0-82a1-11ec-8017-5d554e8551d6",
  "client_secret": "4n0TpfkaedYOkIljy0mtAs4Y2r2qR5XGrBhpt20Cf3LYaE45piAPunlVAq4jbJBV"
}'

The response will contain your access token along with the scheme and expiration period:

{
  "access_token": "eyJhbGciOiJSUz...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Cache the access token

Store the access_token value in your integration cache and reuse it during the time when it remains valid to avoid redundant calls to the token endpoint.

Currently our access tokens are valid for up to 24 hours. In your client, decode the access_token and retrieve the expiration time from the exp claim. When the token is close to expiry, request it again using the token endpoint.

The deprecated expires_in response property is provided for backwards compatibility. The use of this property is discouraged.

To encourage proper authentication token caching, the token endpoint is rate limited more strictly. When this limit is reached, HTTP 429 Too Many Requests is returned. When this happens, retry the call with exponential back-off.

Making calls to APSIS One API

When making calls to other endpoints of this API, provide the cached authentication token as Authorization: Bearer <access token> header. Here's an example:

curl --location --request GET 'https://api.apsis.one/audience/keyspaces' \
  --header 'Authorization: Bearer eyJhbGciOiJSUz...'

Video guide

Here's a video guide that covers all of the above topics:

👍

Have questions?

Contact [email protected] to learn more