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

# Scopes

> Scopes control which endpoints an API key can call.

Each API key carries a set of scopes. Endpoints check the key's scopes before
running, and return `403 Forbidden` with `detail: "API key missing required
scopes: ..."` if any required scope is missing.

## Available scopes

| Scope             | Grants access to                                   |
| ----------------- | -------------------------------------------------- |
| `vouchers:read`   | List vouchers, get a single voucher                |
| `vouchers:write`  | Create vouchers                                    |
| `vouchers:redeem` | Redeem (deduct from balance) a voucher             |
| `products:read`   | List voucher product designs, get a single product |
| `customers:read`  | List customers, get a single customer              |
| `customers:write` | Create and update customers                        |

These six scopes are the complete set. Any other scope value will be rejected
when the key is created.

## Scope-to-endpoint map

| Endpoint                                   | Required scope    |
| ------------------------------------------ | ----------------- |
| `GET /developer/vouchers`                  | `vouchers:read`   |
| `GET /developer/vouchers/{code}`           | `vouchers:read`   |
| `POST /developer/vouchers`                 | `vouchers:write`  |
| `POST /developer/vouchers/{code}/redeem`   | `vouchers:redeem` |
| `GET /developer/products`                  | `products:read`   |
| `GET /developer/products/{product_id}`     | `products:read`   |
| `GET /developer/customers`                 | `customers:read`  |
| `GET /developer/customers/{customer_id}`   | `customers:read`  |
| `POST /developer/customers`                | `customers:write` |
| `PATCH /developer/customers/{customer_id}` | `customers:write` |

## Choosing scopes

Grant a key the minimum scopes it needs for the integration. For example, an
in-store redemption terminal typically only needs `vouchers:read` and
`vouchers:redeem`; it does not need `vouchers:write` or any customer scope.