E-INVOICE - Which token do I need and when do I need to create one?

The integration guide describes two separate token creation steps (Step 4 and Step 7). This can be confusing — especially if your organization is already set up and you just want to send e-invoices. Here's what each token is for and which one you actually need.

The two tokens explained

The API is split into two groups of endpoints: Management and Operation. Each group requires a token scoped to a different level.

Group-level token (Step 4) — for Management

This token is created using the API Key generated in the HUB at the Group level. It authenticates you for the Management endpoints:

• POST /organizations — create an Organization UNIT
• POST /subjects — create a new API Key scoped to a UNIT
• GET /subjects — list existing API Keys

You only need this token during the initial setup when creating your Organization UNIT and generating the UNIT-scoped API Key. Once those resources exist, you don't need to create this token again unless you're onboarding a new UNIT.

UNIT-scoped token (Step 7) — for Operation

This token is created using the API Key that was generated in Step 6 (the one scoped to your Organization UNIT via the X-Scope-Identifier header). It authenticates you for all Operation endpoints:

• POST /taxpayers — create and manage taxpayers
• POST /systems — create and manage systems
• POST /records — create records (intentions, transactions, uploads)
• GET /records/{record_id} — retrieve record status
• All other taxpayer, location, system, record, and file endpoints

Quick reference