# API Scopes

> Every Payments API scope, what it grants, and the hierarchy rules that expand write scopes to include reads.
> Source: https://developers.coinbax.com/docs/api/scopes
> Last updated: 2026-07-16

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:

```bash
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](/docs/api/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](/docs/api/errors).

## 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.