Begin hier
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.
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.