> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instantcompliance.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Least-privilege access control for API keys.

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**:

```json theme={null}
{
  "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.