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 platform administrators.

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.

A single token is issued against a Master Account. You do not rotate it yourself; if you need a fresh one, request that your current token be revoked and re-issued.

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. 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. Hold to the same standard on your side.
• Transport is HTTPS-only. Plain HTTP is not served.
• Request token rotation immediately if you suspect a token may have been leaked.

Confirming which account a token maps to

Call GET /v1/whoami at any time to see the mastercode and mastername behind a credential, without making any change. It is the recommended smoke test after receiving 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.