Authentication
Authenticate every request with an API key sent as an HTTP Bearer token.
Authorization: Bearer rk_live_...
Production keys start with rk_live_. Sandbox keys start with rk_test_. A
key issued for one environment is rejected in the other. Keys are secret
credentials: store them in a secrets manager, never in client-side code or
source control, and rotate them if they are exposed.
Making a request
curl https://api.rookpayments.com/v1/status \
-H "Authorization: Bearer rk_live_..."
The scheme is HTTP bearer with format api key. Do not send a session cookie
or a JWT in place of the API key.
Program scope
Most resources belong to a program. Send that program on every program-scoped request:
X-Program-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Organizations with a single program may omit X-Program-ID. The API uses
that program. Organizations (or API keys) that can access more than one
program must send the header. Omitting it then returns 400 with
code program_required and param X-Program-ID.
GET /v1/status is not program-scoped and does not accept the header.
GET /v1/cards/embed authenticates with session_token instead of an API
key and does not accept X-Program-ID.
Failed authentication
| HTTP | error.code | When |
|---|---|---|
| 401 | authentication_error | Missing header, malformed Bearer value, unknown key, or a sandbox key sent to production (and the reverse). |
| 403 | permission_denied | The key is valid but cannot access the given program or resource. |
error.request_id (also returned as X-Request-ID) when you contact
support.