Generate Access Token

Exchange your API key for a short-lived access token and a refresh token. Call this once at the start of your integration, and again any time your refresh token itself expires or is revoked.

Path parameter: reference — your company reference (given to you at onboarding).

Header: x-api-key — your API key (given to you at onboarding). Keep this secret; it never leaves your backend.

Errors: 400 API key missing · 401 API key expired or invalid · 403 company reference not found.

Path parameter

Header: x-api-key (string, required) - your plain-text API key; compared against a bcrypt hash.

No request body.

Behaviour notes

• Success returns { accessToken, refreshToken } (HTTP 200). Each call rotates the stored refresh token: any refresh token issued earlier stops working.
• An unknown reference returns 400 Bad Request: API key is missing (not 403) because no API-key record exists for it.
• Expired API key: 401 with message Bad Request: API KEY EXPIRED. Wrong key: 401 Unauthorized: Invalid API key.
• Tokens are refused unless the business is live and KYB status is APPROVED or CHANGES_REQUESTED. 403 ACCOUNT_DEACTIVATED is returned only when KYB is APPROVED but the account is switched off; every other refusal is 403 KYB_REQUIRED with the current kybStatus (NOT_STARTED, IN_PROGRESS, SUBMITTED, CHANGES_REQUESTED, REJECTED).
• Unexpected server errors come back as 400 { "message": "Internal Server Error" }.

Errors that apply to every authenticated endpoint (shown here once): 401 Access token is missing (no Authorization: Bearer header), 403 Invalid or expired access token, 403 KYB / deactivated bodies as below (cached for up to 30 s), and 503 Service temporarily unavailable if the KYB check itself fails.