Authentication: tokens, scopes and expiry

The Customer API uses OAuth 2.0 client credentials. You exchange a client ID and secret for a short-lived access token, then send that token on every request. This guide covers the parts the Getting Started page skips: what the token carries, how long to keep it, and what to do when it stops working.

Getting credentials

Credentials are issued by Xace. Ask support for a client ID and secret for your workspace. Each set of credentials is granted a set of scopes that decide what it can do; ask for the smallest set that covers your integration.

Exchanging credentials for a token

curl --location 'https://xace-prod.uk.auth0.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'audience=https://customer-api.prod.xace.io' \
  --data-urlencode 'grant_type=client_credentials'

The response contains access_token, token_type and expires_in (seconds). Send the token as a bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Scopes

Endpoints are gated by scope. The payee scopes are documented in the Payees reference; read scopes for accounts, transactions, approvals and statements follow the same pattern and are confirmed by Xace when your credentials are issued.

A request with a valid token but a missing scope returns 403 Forbidden. A missing or expired token returns 401 Unauthorized.

Caching and refreshing

1. Cache the token in memory with its expiry time. Do not request a new token per API call; the token endpoint is rate limited and each request is slow compared with an API call.
2. Refresh when fewer than a couple of minutes remain, not when it has already expired.
3. On a 401, refresh once and retry once. If the retry also fails, stop and alert. Looping on 401 will lock you out.
4. Never log the token. Log the request ID from the response instead.

Environments

The token endpoint and API base URL above are production. If Xace has provided you with a sandbox, it has its own base URL and credentials; keep the two sets in separate configuration so a sandbox job can never hold a production token.