Authentication

Every request authenticates with a bearer token:

Authorization: Bearer <your_partner_token>

The token both authenticates you and identifies your Master Account. There is no separate masterid on any request — the server derives it from the token. This is why a token is all an integration needs, and also why a leaked token is a full compromise of that Master Account's merchant estate.

How a token is issued

Tokens are issued and revoked by a platform SuperAdmin in the backoffice, against your Master Account. This API does not issue, list, or rotate tokens — that stays a deliberate, human, audited action.

To get a token, or to have one revoked, contact your platform representative. Revocation is immediate: a disabled token stops authenticating on its next request.

The access gate

A request is authenticated only when both of these hold:

1. The token exists and is enabled.
2. The Master Account it belongs to is active (not suspended).

If the account is suspended, every token under it stops working — even an otherwise-valid one. There is no partial access.

Every authentication failure returns the same 401 with the same body:

{
  "error": {
    "code": "unauthorized",
    "message": "A valid bearer token is required.",
    "requestid": "8f3c1a9b2d7e4f60"
  }
}

Unknown token, disabled token, a token for the wrong kind of account, suspended master, malformed header — all identical. The API will not tell a caller why auth failed, because distinguishing the cases would let someone probe the credential store. If your valid token suddenly returns 401, assume it was revoked or your account was suspended, and contact support with the requestid.

Keep the token safe

The stored token is the secret — there is nothing else to verify against it. Treat it like a password:

• Server-side only. Never ship it to a browser, mobile app, or any client you don't control.
• Never log it. The API itself never writes your token to any log or error body, and never echoes it back — responses only ever include the credential id (tokenid), never the value. Hold to the same standard on your side.
• Transport is HTTPS-only. Plain HTTP is not served.
• Rotate on suspicion. If a token may have leaked, have it revoked and a new one issued. Because tokenid distinguishes your credentials, you can roll one token at a time.

Confirming which account a token maps to

Call GET /v1/whoami at any time to see the masterid and tokenid behind a credential, without making any change. It is the recommended smoke test after receiving or rotating a token.

Rate limits

Authenticated requests are rate-limited per credential, so one token's traffic cannot exhaust another's. Exceeding the limit returns 429 with a Retry-After header. See Rate limits.