# Authenticatie en sleutels

Bearer-sleutels, scopes per resource, profielbeperking en hoe je sleutels veilig beheert.

## Bearer-token

Elk verzoek naar `/api/v1/…` stuurt de sleutel in de `Authorization`-header. De API controleert de sleutel, het pakket van je organisatie en het aantal verzoeken in het huidige minuutvenster.

```http
Authorization: Bearer cijfr_live_…
```

Sleutels maak en beheer je onder Instellingen, dan API. Je ziet per sleutel het voorvoegsel (zoals `cijfr_live_a1b2`), niet de sleutel zelf. Verwijderen is intrekken: de sleutel werkt direct niet meer.

## Scopes

Een sleutel heeft rechten per resource. `write` impliceert `read`: wie `invoices:write` heeft, mag facturen ook lezen. Kies je niets, dan krijgt een nieuwe sleutel `invoices:read` en `invoices:write`.

| Scope | Geeft toegang tot |
| --- | --- |
| `customers:read` / `customers:write` | Klanten lezen en aanmaken |
| `products:read` / `products:write` | Producten lezen en aanmaken |
| `invoices:read` / `invoices:write` | Facturen lezen en aanmaken |
| `subscriptions:read` / `subscriptions:write` | Terugkerende schema's |
| `checkouts:read` / `checkouts:write` | Hosted checkout-sessies |
| `credits:write` | Posttegoed, alleen voor Cijfr zelf |

Ontbreekt de scope, dan antwoordt de API met `403` en `forbidden`. `GET /api/v1/me` vraagt geen scope.

## Sleutel beperken tot één profiel

Een organisatie kan meerdere Cijfr-profielen hebben (handelsnamen). Bij het aanmaken van een sleutel koppel je hem eventueel aan één profiel. Die sleutel ziet en schrijft dan alleen documenten van dat profiel, en `me` geeft het `profileId` terug.

## Veilig omgaan met sleutels

- Bewaar de sleutel in een omgevingsvariabele of secret-manager, nooit in je repository.
- Roep de API alleen aan vanaf je eigen server of edge function. In browser- of app-code kan iedereen de sleutel uitlezen.
- Geef elke integratie een eigen sleutel met alleen de scopes die hij nodig heeft.
- Verloopt of lekt een sleutel, maak dan een nieuwe en trek de oude in.