Access tokens

Issue a short-lived bearer token, use it, and refresh it by re-issuing.

Protected requests use a short-lived bearer token. You obtain it from the public token endpoint by exchanging your client credentials.

Issue a token

POST /v1/auth/token does not require a bearer token — you don’t have one yet. It does require x-zeam-auth: every request to the gateway needs it, with no exception for token issuance.

x-zeam-auth · string · required

Your application secret. See API keys.

clientId · string · required

Your application’s client ID.

clientSecret · string · required

Your application’s client secret.

cURL

curl -sS https://api.zeam.money/gw/v1/auth/token \
  -H "Content-Type: application/json" \
  -H "x-zeam-auth: $ZEAM_APP_SECRET" \
  -d '{
    "clientId": "11111111-1111-1111-1111-111111111111",
    "clientSecret": "$ZEAM_CLIENT_SECRET"
  }'

Response

{
  "accessToken": "eyJ0eXAiOiJKV1Qi...",
  "tokenType": "Bearer",
  "expiresIn": 3599,
  "associationId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

accessToken · string

The bearer token. Send it as Authorization: Bearer <accessToken>.

tokenType · string

Always Bearer.

expiresIn · integer

Seconds until the token expires.

associationId · string

The association bound to your application, resolved server-side from your bearer token on every request afterward. Informational only — you never send it anywhere.

Use a token

Send the token with your application secret on every protected request:

cURL

curl -sS https://api.zeam.money/gw/v1/wallets \
  -H "Authorization: Bearer $ZEAM_TOKEN" \
  -H "x-zeam-auth: $ZEAM_APP_SECRET"

Refresh a token

Tokens are short-lived and there is no refresh token. To refresh, call POST /v1/auth/token again with your client credentials and use the new token.

Cache the token server-side and reuse it until shortly before expiresIn elapses, then request a new one. Re-issuing on every request is unnecessary and may hit rate limits.

Errors

The token endpoint can return:

• 400, the request body is malformed.
• 401, the client credentials are invalid.
• 502, the request could not be completed. Safe to retry.

All errors use the RFC 7807 problem format.