401 Unauthorized when the key does not carry the permission the target endpoint requires, so pick the minimum set your integration needs.
Keys created before permissions existed carry no permissions and keep access to every endpoint, so no action is required for older keys. Provision a fresh key from the dashboard to opt into the scoped model.
How the check works
- Header: requests carry the key in
x-api-key(see Authentication). - One permission per endpoint: each endpoint requires the permission listed below and accepts no broader substitute. Two rows work differently:
POST /transactionrequires the permission for the transactiontypeyou send, and the sandbox-only simulate endpoint accepts either of two permissions. - Failure mode: a key missing the required permission is rejected with
401 Unauthorized, exactly the same shape as an unrecognised, malformed, revoked, or disabled key. The API does not distinguish those cases on the wire.
Rates, transaction quotes, settlement advice, media uploads, payment method deletion, and payment batches each have their own permission. Select it when you create the key. See Choosing permissions in the dashboard for how the dashboard’s access levels map to these permissions.
Endpoint permission reference
Choosing permissions in the dashboard
When you create a key under Developer → API keys, you pick an access level for each resource: None, Read, or Write. Write includes Read. Each level grants the API permissions below.- Some resources have only a Write level. Deposits, Withdrawals, Swaps, Checkout sessions, and File uploads grant no read permission.
- Levels apply to a whole resource. You cannot grant create without delete on the same resource.
- You can only grant what you hold. A level is offered only if you hold every permission in it, so a teammate without a permission cannot give it to a key.
Start from a preset
The key form offers three starting points. You can adjust any level afterwards.
A payout needs a recipient, and a recipient is a payment method on a customer. That is why the Payouts preset also includes Customers and Payment methods.
