Guides

API Scopes

Every Payments API scope, what it grants, and the hierarchy rules that expand write scopes to include reads.

Last updated 2026-07-16View as Markdown

Every Payments API credential (API key or OAuth client) carries a set of scopes that bound what it can do. Endpoints declare required scopes; a request whose credential lacks them is rejected with 403 before any business logic runs.

Scopes follow the format <action>:<resource>, for example write:transactions.

All scopes

Transactions

Scope Grants
read:transactions View transactions and their status
write:transactions Create and update transactions
cancel:transactions Refund transactions
rescind:transactions Rescind transactions during hold period

Customers

Scope Grants
read:customers View customer information
write:customers Create and update customers

Templates

Scope Grants
read:templates View payment templates
write:templates Create and update templates

Disputes

Scope Grants
read:disputes View disputes
write:disputes Create and respond to disputes
submit:evidence Submit evidence for disputes

Webhooks

Scope Grants
read:webhooks View webhook configurations
write:webhooks Create and update webhooks

Compliance

Scope Grants
read:compliance View compliance verifications
write:compliance Create compliance verification requests

Platform

Scope Grants
read:platform View own platform information
write:platform Update own platform settings
manage:api-keys Create and revoke API keys

Admin

Scope Grants
admin:platform Full platform access (all scopes)

Hierarchy rules

You never need to list a read scope alongside its write scope. Write-class scopes automatically include the corresponding read scope:

This scope Also grants
write:transactions read:transactions
cancel:transactions read:transactions
rescind:transactions read:transactions
write:customers read:customers
write:templates read:templates
write:disputes read:disputes
submit:evidence read:disputes
write:webhooks read:webhooks
write:compliance read:compliance
write:platform read:platform
manage:api-keys read:platform

admin:platform grants every scope. It exists for administrative tooling; do not use it for day-to-day integrations.

Defaults

New API keys are created with read-only scopes unless you specify otherwise:

  • read:transactions
  • read:customers
  • read:platform

Request write scopes explicitly at key creation:

curl -X POST https://api-staging.coinbax.com/api/v1/auth/api-key \
  -H "X-API-Key: $COINBAX_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments Integration",
    "scopes": ["read:transactions", "write:transactions", "read:customers"]
  }'

OAuth clients declare their scopes at creation the same way, and a token request can narrow them further with the optional scope parameter. See authentication.

When a scope is missing

A request without the required scope returns 403 with the code INSUFFICIENT_SCOPES. The error message names the scopes the endpoint requires and the scopes your credential actually has, so the fix is always explicit:

Insufficient permissions. Required scopes: [write:transactions].
Your key has: [read:transactions, read:customers]

Handle 403 distinctly from 401: a 401 means the credential itself is invalid, a 403 means the credential is valid but under-scoped. See errors and the response envelope.

Practices that hold up

  1. Least privilege. Grant only the scopes the integration uses.
  2. One key per integration. Separate keys mean a leak or a revocation affects one system, and audit logs attribute activity cleanly.
  3. Start read-only. Ship against the default read scopes, then add write scopes as flows come online.
  4. Reserve admin:platform. Administrative tools only.