Authentication

Every request must carry a credential. The API supports two authentication schemes — use one, never both on the same request.

API keys

API keys are provisioned from the Atlas dashboard. Each key is scoped to a single merchant (or a single terminal, depending on your security posture). Keys come in two flavors: sk_live_ for production and sk_test_ for sandbox. They never expire, but they can be rotated — old keys continue to function for 24 hours after rotation to give you a deployment window.

curl $BASE_URL/v1/device/health \
  -H "X-Api-Key: sk_live_9f8e7d6c5b4a3210..."

Bearer JWT (cloud mode)

For cloud-connected integrations, exchange your client credentials for a short-lived JWT. The token is scoped to a specific terminal and a set of permission scopes. Issue a POST to the Atlas auth server:

curl https://auth.atlas-softpos.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_01JQABC123456",
    "client_secret": "cs_live_...",
    "scope": "terminal:read terminal:write transactions:write",
    "terminal_id": "TID-00012345"
  }'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "terminal:read terminal:write transactions:write",
  "terminal_id": "TID-00012345"
}

Then attach the token as a Authorization: Bearer header on every Commerce API request:

curl $BASE_URL/v1/transaction/sale \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "SALE", "amount": 2500, "currency": "NZD" }'

Token endpoint

Permission scopes

Request only the scopes your integration needs. A POS that only runs sales and reads health should request terminal:read transactions:write. The principle of least privilege limits the blast radius if a token is leaked.

Key management

• API keys are rotated from the dashboard. Old keys remain valid for 24 hours after rotation.
• JWT client secrets can be rotated independently. Both old and new secrets work during the 24-hour overlap.
• Every request is logged with the credential fingerprint. The audit trail shows which key or token was used, when, and from which IP.
• Keys and tokens never appear in logs or error messages. If you suspect a leak, rotate from the dashboard immediately.
• Sandbox keys (sk_test_, cs_test_) only work against the sandbox. They cannot be used against production endpoints, and vice versa.

WebSocket authentication

WebSocket connections authenticate via the same two schemes. Send the credential on the initial HTTP upgrade request — either as an X-Api-Key header or an Authorization: Bearer header. If your WebSocket client does not support custom headers on the upgrade, append the key as a query parameter: ?apiKey=sk_live_.... The connection is authenticated once at upgrade time; you do not need to re-authenticate per message.