Skip to main content
Every API key is scoped to a configurable set of permissions chosen when the key is created in the Dashboard. Requests are rejected with 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 /transaction requires the permission for the transaction type you 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.
POST /transaction checks the transaction type. A key needs the permission for the type it creates: TRANSACTION.DEPOSIT.CREATE for a DEPOSIT, TRANSACTION.SWAP.CREATE for a SWAP, and TRANSACTION.WITHDRAW.CREATE for anything else (a request with no type is treated as a withdrawal). A key that holds only the deposit permission cannot create a withdrawal. If a request that used to work now returns 401, check that the key holds the permission for the type you send.
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.
Managing keys? Head to Developer → API keys in the Dashboard to create, rotate, or revoke them.