Authentication

Organization API keys

Keys created under Developer → API keys are organization API keys (pk_…). Send Authorization: Api-Key <pk_…> on every authenticated API request. For taxpayer-specific operations, also send x-ae-taxpayer-id: <txpay_…>, even when your organization has only one taxpayer. This applies in Live and Sandbox.

Operation	Required headers with an organization API key
Send, validate, list or retrieve documents; reports; taxpayer settings	`Authorization` and `x-ae-taxpayer-id`
A taxpayer's Business Card or Directory listing	`Authorization` and `x-ae-taxpayer-id`
List connected taxpayers or grants	`Authorization` only

Create the key in the same portal mode as the taxpayer. Obtain its Taxpayer ID from Taxpayers → taxpayer details → Taxpayer ID, or taxpayer_id in GET /taxpayers after consent. An allocated ID alone does not authorize access: onboarding must be complete and your organization must hold an active grant with the required scopes. The taxpayer must be active.

Use the opaque txpay_… value, not the TIN, 0235:<TIN>, or organization ID. participant_id (0235:<TIN>) identifies the taxpayer on the Peppol network; it is not the Taxpayer ID.

Taxpayer access and OAuth

Taxpayers are not owned by an organization. They approve your organization's access and scopes on the Wafeq e-invoicing ASP consent screen. Use the connection flow: authorization code with PKCE (S256 only), followed by a server-side exchange at POST /oauth/token.

Send Authorization: Bearer <access_token> to act for the one taxpayer named by that token. The x-ae-taxpayer-id header is then optional.

Scope	Access
`taxpayer:read`	Read taxpayer details
`invoices:read`	Read every document of the taxpayer, including documents other organizations issued
`invoices:write`	Send, validate and change documents
`inbound:read`	Read documents other access points sent to the taxpayer

An organization API key with x-ae-taxpayer-id acts through all of that organization's active grants on the taxpayer. Add x-ae-grant-id: <tgr_…> to act through a single grant, so revoking it immediately stops those requests. An API key never bypasses consent.

Disconnecting and credential storage

Disconnect a taxpayer with DELETE /grants/{grant_id}. Requests outside your grants, or after the taxpayer revokes your access, return 403. Subscribe to taxpayer webhooks and reconcile grants when access changes.

Keep API keys, client secrets, access tokens and refresh tokens on your server. Use the matching Live or Sandbox OAuth client and credentials. Never embed secrets in browser code, mobile apps, URLs or logs.