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

​
Available scopes

ScopeRoutes it unlocks
customers:writePOST /v1/customers, PATCH /v1/customers/{id}
customers:readGET /v1/customers, GET /v1/customers/{id}
aml:readGET /v1/customers/{id}/aml

​
Choosing the right combination

Integration typeScopes
Ingest only (“push customers from my CRM”)customers:write
Sync results back (“pull KYC status into my CRM”)customers:read aml:read
Both directionscustomers:write customers:read aml:read
Reporting / dashboards onlycustomers: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:
ScopeBacking permission the issuer must hold
customers:writecustomers.add
customers:readcustomers.view
aml:readcustomers.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.