Skip to main content

Using Access Tokens

Request access tokens and use them to call APIs

Overview

Use this guide to request an OAuth access token and use it to call our APIs.

Before you start, make sure you have completed the previous guides: Network Access (mTLS & IP) and Authentication (OAuth 2.0)

To request an access token, you will need:

  • client_id
  • kid
  • Private signing key
  • Token endpoint URL
  • Required API scopes

How access tokens work

Access tokens are issued using the OAuth 2.0 client credentials flow.

At a high level:

  1. Your system creates a signed JWT client assertion
  2. Your system sends a token request to the token endpoint
  3. The token endpoint returns an access token
  4. Your system includes the access token when calling an API
Step 1

Request an access token

We will provide you with the Discovery Endpoint and Token Endpoint URLs for your environment.

Before calling an API, request an access token. Your request must include a signed JWT client assertion:

{
  "kid": "<<kid>>", // Key ID of the private key used to sign the JWT
  "alg": "ES256"   // Signing algorithm — ES256 as signed with Elliptic Curve certificate
}.{
  "iss": "<<client_id>>",      // Issuer
  "sub": "<<client_id>>",      // Subject
  "aud": "<<token_endpoint>>", // Audience — set to the Token Endpoint
  "iat": 1664328998,           // Issued At — current time (seconds since epoch)
  "exp": 1664332598            // Expiration Time — now + 3600 (1 hour in seconds)
}.[Signature] // Signed with Elliptic Curve key

Your request must include:

  • grant_type=client_credentials
  • client_id
  • client_assertion_type
  • client_assertion (a signed JWT created using your private key)
  • scope

This request must be made using your mTLS certificate.

Sample token request

set -u && curl --request POST '<<token_endpoint>>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --cert "${mtlsCert}" --key "${mtlsKey}" --pass "${mtlsKeyPassphrase}" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=${clientId}" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=${clientAssertion}" \
  --data-urlencode "scope=${scopes}"

Sample token response

{
  "access_token": "<<access_token>>",
  "token_type": "Bearer",
  "expires_in": 119
}
Step 2

Use the access token

Include the access token in the Authorization header when calling an API:

Authorization: Bearer <<access_token>>

Example API request

curl --request POST "${api_endpoint}" \
  --header "Authorization: Bearer ${access_token}" \
  --header "Content-Type: application/json" \
  --data '{ ... }'

Token expiry and caching

Access tokens are short-lived (typically under 2 minutes, based on expires_in).

You should:

  • Cache the token
  • Reuse it until it expires
  • Request a new token only when required

Avoid requesting a new token for every API call.

Token caching

Access tokens are valid for under 2 minutes (expires_in seconds). Cache your token and reuse it for the duration of its lifetime to avoid unnecessary requests.

Common issues

Token request fails

Likely causes:

  • Invalid client_id
  • Incorrect or expired client assertion
  • Wrong token endpoint
  • Missing or incorrect scope
  • mTLS certificate not configured correctly
  • Request not sent from a whitelisted IP

API request is rejected

Likely causes:

  • Access token expired
  • Missing Authorization header
  • Scope does not allow access to the API

Ready to start building?

Continue your API implementation with these guides: