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

# Scopes

> What each API key permission grants.

An API key carries one or more **scopes** — the same permissions shown when you create a
key in the dashboard's **API Keys** screen. A [Bearer token](/authentication) can only
access endpoints whose required scope it holds; otherwise the request returns `403`.

| Scope           | Grants access to                      | Key endpoints                                                 |
| --------------- | ------------------------------------- | ------------------------------------------------------------- |
| `pay`           | Collect payments from customers       | `POST /pay`                                                   |
| `deposit`       | Disburse funds to customers (top-ups) | `POST /deposit`                                               |
| `balance`       | Read balance and transaction history  | `GET /balance`, `GET /transactions`, `GET /transactions/{id}` |
| `payout`        | Create and manage payouts             | `POST /payouts`, `GET /payouts`, approve/cancel               |
| `beneficiaries` | Manage saved payout recipients        | `/beneficiaries` CRUD                                         |
| `bulk_pay`      | Batch disbursements                   | `/bulk/batches` create, add recipients, process, cancel       |
| `payment_links` | Hosted payment pages                  | `/payment-links` CRUD                                         |
| `team`          | Manage dashboard team members         | `/team`, `/team/invite`, roles                                |
| `webhooks`      | Register/manage webhook endpoints     | `/webhooks` CRUD, test                                        |
| `settings`      | Read/update account settings          | `GET /settings`, `PUT /settings`                              |

<Note>
  All paths above are under `/merchant/api`. Every endpoint except
  [`POST /merchant/api/auth`](/authentication) and `GET /merchant/api/status` requires a
  Bearer token with the matching scope.
</Note>

## Choosing scopes

Grant the **least privilege** needed:

* A checkout integration that only collects payments needs `pay` (plus `balance` to
  reconcile, and `webhooks` to receive settlement events).
* A payroll integration needs `payout` or `bulk_pay` and `beneficiaries`.
* A read-only reporting tool needs just `balance`.

You choose scopes twice: when **creating the key** (the maximum it can ever use) and
optionally when **requesting a token** via `/auth` (a subset for that token).