API Authentication & Security

Authenticate every request to the Rook API with an API key sent as an HTTP Bearer token. All requests must be transmitted over TLS 1.3 (HTTPS).

Bearer API Key Header

Include your key in the Authorization header using the standard Bearer scheme:

Authorization: Bearer rk_live_92fa8b30e4c194bb10842f

Sandbox Keys (`rk_test_...`)

Used exclusively on https://api.sandbox.rookpayments.com. Generates simulated transactions, cards, and ledgers with zero real money movement.

Production Keys (`rk_live_...`)

Used exclusively on https://api.rookpayments.com. Connects directly to live Federal Reserve FedNow, ACH, and card network clearing.

A key issued for one environment is immediately rejected in the other. Keys are secret credentials: store them in a secrets manager, never in client-side code or public source repositories.

Multi-Tenant Program Scope (`X-Program-ID`)

Most resources (wallets, cards, ledger transfers) belong to a specific Program. Pass your program UUID in the X-Program-ID header with every program-scoped request:

X-Program-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Organizations with a single program may omit X-Program-ID (the platform defaults to your single partition). Organizations or API keys with access to multiple programs must send the header. Omitting it returns HTTP 400 with code: "program_required" and param: "X-Program-ID".

Making an Authenticated Request

curl https://api.sandbox.rookpayments.com/v1/status \
  -H "Authorization: Bearer rk_test_..." \
  -H "X-Program-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7"

Authentication Failure Reference

HTTP	error.code	Condition
401	authentication_error	Missing header, malformed `Bearer` token, unknown key, or cross-environment key mismatch.
403	permission_denied	The key is valid but lacks access to the requested program partition or resource.