Authentication
Send your API key as a bearer token on every request:
Authorization: Bearer pk_live_<partner_id>.<key_id>.<secret>
Copy the full token from Console → Keys when you create or rotate a key. Use
the token that matches the environment you are calling: pk_test_… for the
sandbox, pk_live_… for production.
Token format
The token starts with a mandatory mode prefix (pk_live_ or pk_test_) followed
by three dot-separated parts:
| Part | Example | Notes |
|---|---|---|
pk_live_ / pk_test_ | pk_live_ | Mode prefix. pk_live_ for production, pk_test_ for the sandbox. Required. A token without it is rejected with auth_invalid_format. |
<partner_id> | acme | Your partner id. |
<key_id> | k_7Yh2 | Identifies which key is in use (keys are rotatable). |
<secret> | s_3Fb… | The secret. Shown only once, at issue time. |
Store the secret safely
The full token is shown once, at issue time, and cannot be recovered. If a
secret leaks, revoke the key and issue a new one; secrets cannot be reset in
place. Keys and partners can be revoked; either returns auth_revoked (HTTP 401).
Auth failures
Auth and availability failures return one of these code values:
| Status | code | Meaning |
|---|---|---|
| 401 | auth_missing | No Authorization header. |
| 401 | auth_invalid_format | Header present but not a well-formed pk_live_… / pk_test_… token (the mode prefix is required). |
| 401 | auth_unknown_partner | No partner exists for that id. |
| 401 | auth_revoked | The partner or the key has been revoked. |
| 401 | auth_bad_secret | Unknown key id, or the secret did not match. |
| 403 | auth_partner_not_approved | The partner account is still pending approval; no endpoint works until approved. |
| 503 | service_unavailable | The service is briefly unavailable; retry after the delay in Retry-After. |
See Error handling for the full envelope and retry guidance.