Authentication · Access token

Exchange credentials for an access token

Authenticate your POS agent with its Client ID and public key to receive a bearer token, then send it as Authorization: Bearer on API calls.

Keep authentication server-side

Never place the public key or an access token in browser or mobile code. Redact the Authorization header from logs.

Authorization sequence

Get your POS credentials

Enable POS to receive a Client ID and public key (see API keys).

Authenticate

POST them to the authenticate endpoint and read data.token.

Call the API

Send the access_token as a bearer token on each request.

Authenticate a POS agent

POST/api/v1/organizations/pos/authenticate

Body: clientId and publicKey, both required.

This endpoint takes no bearer token. A 200 response carries the usual envelope, and the token is at data.token. Get the credentials from API keys.

Token response and expiry

data.token follows the AccessTokenResponse schema: access_token, expires_in, refresh_expires_in, refresh_token, token_type, id_token, session_state, and scope. The schema does not state a fixed lifetime, so always read expires_in (seconds) from the response.

Refresh tokens for POS agents

The API specification does not say whether a POS token comes with a usable refresh token or how it is renewed. If refresh_token is empty, or a request returns 401, authenticate again with your Client ID and public key.

Store and renew securely

Cache the token in server memory
Track expires_in at runtime
Renew before it expires

Don't

Persist it in client storage
Log bearer tokens
Hard-code a lifetime

Use the bearer token

Send Authorization: Bearer <access_token> and the X-Client-Id header (your organization's reference) on organization-scoped calls. POS agents create and read invoices under /api/v1/organizations/{organizationReference}/invoices/pos.

Expected result: 200

The request succeeds with the standard envelope, and the invoice data is in data. See Create an invoice.

People signing in (and the management calls on the API keys page) use a different flow. The token has the same AccessTokenResponse shape.

POST/api/v1/auth/login

Body email, password, optional code. Returns requiresMfa, requiresPasswordReset, and token.

POST/api/v1/auth/login-otp

When an emailed code is needed, send it here to receive the access token.

POST/api/v1/auth/refresh

Header X-Client-Id, body { "refreshToken": "..." }. Returns a new token and revokes the current access token.

POST/api/v1/auth/logout

Header X-Client-Id. Logs out and revokes the current access token.

Authentication errors

Errors use the standard envelope with successful: false and a message. The API documents 400, 401, 403, 404, 409, and 500. A 401 usually means the token or credentials are missing, wrong, or expired, so authenticate again. A 400 usually means a required field is missing from the body. See Errors.