Authentication and scopes

API keys

An owner or admin creates keys in the app under Instellingen › API-sleutels (Settings › API keys). A key looks like this:

ep_1a2b3c4d_0123456789abcdef0123456789abcdef
   └prefix8┘ └──────────── secret32 ────────────┘

The full key is shown once. EuroPlaybook stores only a SHA-256 hash.
The prefix stays visible in the app and in the audit log, so you can tell keys apart.
A key can have an expiry date and can be revoked at any time. Revoked or expired keys get 401.

Sending the key

Every request sends the key as a Bearer token:

GET /v1/account HTTP/1.1
Host: api.europlaybook.com
Authorization: Bearer ep_1a2b3c4d_0123456789abcdef0123456789abcdef

The account is taken from the key. There is no account id in the path. Keep keys out of source control and front-end code; use an environment variable such as EUROPLAYBOOK_API_KEY.

Scopes

Scope	Allows
`catalogue:read`	Products, product groups, packaging, packaging items, evidence, regime profiles, reference codes
`catalogue:write`	Create and update products by SKU; propose packaging and regime profiles
`sales:read`	Read sales lines
`sales:write`	Send sales lines (bulk, idempotent on `external_id`)
`compliance:read`	Legal entities, obligations, reporting periods and their totals
`reports:read`	Filing packs (read and download)

GET /account works with any scope; use it to check a key.

Scopes ∩ role

A key’s effective rights are its scopes intersected with the current role of the person who created it:

Owners, admins and members can use every scope. Accountants and readers (readonly) only the :read scopes, so a key with catalogue:write whose creator is now a reader can only read.
If the creator leaves the account, all their keys stop working.

What a key can change

Written directly: product data (PUT /products/by-sku/{sku}) and sales lines (POST /sales).
Proposed only: packaging lines and regime profiles are stored with state: proposed and source: api. They show up in the app (“via API”) for a person to confirm.
Never: confirming packaging, locking figures, approving packs and marking them filed. This keeps a person responsible for every filing.

Errors

Status	Meaning
`401`	Missing, malformed, expired or revoked key
`403`	The key’s scopes or the creator’s role do not allow this

See errors for the full format. Exact codes are in the API reference.