Authentication & Security

🧱 Required headers

Every request to the Falco API must include two mandatory headers:

X-Falco-App-Secret: <app_secret>
X-Falco-Api-Key: <api_key>

Header	Description
X-Falco-App-Secret	Secret key associated with your application (production or sandbox). Always keep this private.
X-Falco-Api-Key	API key generated by a Falco customer, linked to their organization AND your application.

🪪 Creating a Developer Application

From the Developer Portal, create a new Application to get your credentials:

Field	Description
Name	Application name (displayed in Falco)
Description	Short description of your integration
URL (optional)	Public page introducing your integration
Scopes	Permissions requested by your app

Once created, your application will have:

An Application ID like app_xxxxxx
Two Application Secrets: one for Production, one for Sandbox

🔒 Available Scopes

Each application must request specific scopes that define what it can access through the Falco API.
When a Falco customer grants access to your application, the API keys generated for that application will include only the approved scopes.

Scopes follow a fine-grained permission model, organized by entity (customers, articles, quotes, invoices, etc.).
You can request only the ones your integration truly needs.

🧩 Unit scopes

Scope	What it allows
`customers:read`	Read/search/list customers and fetch a single customer’s details.
`customers:write`	Create or update customers (names, identifiers, addresses, contacts, etc.).
`customers:delete`	Delete a customer record (soft delete if supported).
`articles:read`	Read/search/list articles (products/services) and fetch a single article’s details.
`articles:write`	Create or update articles (reference, description, pricing, VAT rate, etc.).
`invoices:read`	Read/search/list invoices and fetch a single invoice (metadata, lines, totals, status).
`invoices:write`	Create or update invoices (including rows, VAT, payment info).
`invoices:attachments:read`	List/download attachments associated with an invoice.
`invoices:attachments:write`	Upload/replace/delete attachments on an invoice.
`invoices:send`	Dispatch an invoice (e.g., submit over Peppol / mark as sent).
`invoices:ingest:ubl`	Upload a pre-built UBL invoice for validation/storage and optional sending.
`invoices:ingest:pdf`	Upload a PDF invoice with required metadata so Falco generates a valid UBL, then optionally send.
`peppol:participants:read`	Check whether a recipient is registered on Peppol (participant lookup).

🌐 Aggregate (alias) scopes

Aggregate scope	Expands to
`customers:write`	`customers:read`, `customers:write`
`articles:write`	`articles:read`, `articles:write`
`invoices:write`	`invoices:read`, `invoices:write`, `invoices:attachments:read`, `invoices:attachments:write` (+ `invoices:delete` if enabled)
`invoices:attachments:write`	`invoices:attachments:read`, `invoices:attachments:write`

⚠️ Best practices

Never share your App Secret publicly
Use environment variables to store credentials
Keep sandbox and production secrets strictly separate
Immediately revoke exposed keys