Scopes

Every API key is issued with one or more scopes. Scopes determine which routes the key can call.

Available scopes

Scope	Routes it unlocks
`customers:write`	`POST /v1/customers`, `PATCH /v1/customers/{id}`
`customers:read`	`GET /v1/customers`, `GET /v1/customers/{id}`
`aml:read`	`GET /v1/customers/{id}/aml`

Choosing the right combination

Integration type	Scopes
Ingest only (“push customers from my CRM”)	`customers:write`
Sync results back (“pull KYC status into my CRM”)	`customers:read aml:read`
Both directions	`customers:write customers:read aml:read`
Reporting / dashboards only	`customers:read aml:read`

A reporting integration with only the read scopes physically cannot create or modify records — useful when sharing a key with a third party or a BI tool.

Backing permissions

Scopes are not free-standing — each maps to a granular internal permission in the role model. When an admin issues a key, the chosen scopes are checked against the admin’s own permissions:

Scope	Backing permission the issuer must hold
`customers:write`	`customers.add`
`customers:read`	`customers.view`
`aml:read`	`customers.view`

This prevents an admin with org.api-keys but limited customer access from minting a key that bypasses their own gates.

Error when a scope is missing

If a request authenticates successfully but the key lacks the scope the route requires, you get 403 forbidden_scope:

{
  "error": {
    "code": "forbidden_scope",
    "message": "This API key does not have the required scope: customers:write.",
    "details": { "required_scope": "customers:write" }
  }
}

The fix: rotate the integration to a key that includes the missing scope. Existing keys cannot be edited — issue a new one with the right scopes and retire the old one.

Get started

Core concepts

Webhooks

AI assistants

Available scopes

Choosing the right combination

Backing permissions

Error when a scope is missing

​Available scopes

​Choosing the right combination

​Backing permissions

​Error when a scope is missing

Available scopes

Choosing the right combination

Backing permissions

Error when a scope is missing