API keys and scopes

Every partner key carries a set of scopes (permissions) following the least-privilege principle. An agent endpoint requires a specific scope: if the key doesn't have it, the call returns 403 FORBIDDEN. You choose scopes when creating a key in the partner portal.

Scope catalog

This is the full list of scopes a partner can assign to a key (in resource → action order). The endpoint rejects the call if the key is missing the listed scope.

Scope	What it allows
`invoice:read`	Read invoices (list, detail), Peppol statuses/received documents, and vehicles: `GET /agent/invoices`, `/agent/invoices/{id}`, `/agent/peppol/status`, `/agent/peppol/received`, and the whole `/agent/vehicles/*` group (list, detail, by-plate).
`invoice:create`	Issue an invoice: `POST /agent/invoices`.
`invoice:update`	Edit an invoice's content (`PATCH /agent/invoices/{id}`: items, dates, notes; camelCase payload), change its status (`PATCH /agent/invoices/{id}/status`) and manage attachments: add/remove (`POST`/`DELETE` `/agent/invoices/{id}/attachments`).
`invoice:send`	Send over Peppol (`POST /agent/peppol/send`, `/send/batch`), Peppol `enroll`, reminders, and `POST /agent/organizations/{id}/peppol-claim` (resend the Financial Administration confirmation).
`invoice:download`	Download an invoice's PDF and XML: `GET /agent/invoices/{id}/pdf`, `/agent/invoices/{id}/xml`.
`contact:read`	Read customers (list, detail): `GET /agent/customers`.
`contact:create`	Create a customer: `POST /agent/customers`.
`receipt:read`	Read received documents / vendors (list, detail, stats, QR): `GET /agent/expenses`, `/agent/vendors`.
`receipt:create`	Upload a received document and create a vendor: `POST /agent/expenses/upload`, `/agent/vendors`.
`receipt:update`	Edit / reclassify a received document, including bulk operations (`bulk`).
`receipt:approve`	Approve a received document.
`contract:read`	Read contracts: `GET /agent/contracts`, detail, payment schedule, linked invoices, stats, and attachment downloads.
`contract:create`	Create a contract (`POST /agent/contracts`) and AI extraction from PDF (`POST /agent/contracts/extract`).
`contract:update`	Edit a contract and its payments (`PATCH /agent/contracts/{id}`, `PATCH /agent/contracts/payments/{paymentId}`), extend the schedule, and upload/delete attachments.
`contract:delete`	Delete a contract: `DELETE /agent/contracts/{id}`.
`report:read`	Read reports / dashboard summary: `GET /agent/dashboard/summary`.
`org:provision`	Create a client organization (`POST /agent/organizations`) and send the Financial Administration activation token (`POST /agent/organizations/{id}/activation-token`).

Default scope set

A newly created partner key (via admin "partner registration" or self-service in the portal) gets read + create across the agent surface. By default that's:

invoice:read
invoice:create
invoice:update
invoice:send
contact:read
contact:create
receipt:read
report:read
contract:read
contract:create
contract:update
org:provision

What to watch out for

The default key does not have invoice:download or contract:delete. If you need to download invoice PDF/XML or delete contracts, request these scopes when creating the key. Otherwise these calls return 403 FORBIDDEN. Keys created before contracts were introduced (August 2026) carry no contract scopes: create a new key.

POST /agent/organizations/{id}/peppol-claim requires invoice:send, not org:provision. It only (re)sends the confirmation email for an org the key already owns; it does not create an organization. Details in Production onboarding.

Treat a scope 403 as a configuration error: regenerate the key with the correct scope set, don't retry the call in a loop. More in Error codes.