Permissions
Scope each API key to the resources and actions it needs. A key without the right permission gets 403.
Every key holds a set of permissions, chosen when you create it and editable later from the key's menu in Dashboard → Developers → API keys. Each endpoint in the API reference lists the permission it needs.
- Write includes read. Granting
checkouts:writealso grantscheckouts:read. - Changes apply to the next request. You don't need a new secret after editing a key's permissions.
- New keys get the Checkouts permissions unless you change them, which covers everything the API does today.
Scopes
| Resource | Permissions | Covers |
|---|---|---|
| Checkouts | checkouts:read, checkouts:write | Create and retrieve hosted checkout sessions. In the API now. |
| Payments | payments:read | Payment history, statuses and fees. |
| Refunds | refunds:read, refunds:write | Refund records and issuing refunds. |
| Customers | customers:read, customers:write | Buyer profiles and their purchase history. |
| Products | products:read, products:write | Catalog, prices and inventory. |
| Subscriptions | subscriptions:read, subscriptions:write | Plans, renewals and cancellations. |
| Payouts | payouts:read | Balances and payout schedule. |
| Webhooks | webhooks:read, webhooks:write | Endpoints and delivery logs. |
| Analytics | analytics:read | Revenue, conversion and reports. |
Scopes other than Checkouts take effect as their endpoints launch, so a key you scope today keeps working without edits.
Missing permissions
A valid key without the permission an endpoint needs gets 403:
{
"ok": false,
"error": {
"code": "forbidden",
"message": "This API key doesn't have the checkouts:write permission. Add it in Dashboard → Developers → API keys."
}
}Choosing scopes
- A server that only sells:
checkouts:write. - A job that only checks orders:
checkouts:read, so a leak can't create sessions. - Separate keys per service, each with the smallest set that works, so you can revoke one without touching the rest.