---
updatedAt: 2025-10-27T14:38:56.000Z
agentTools:
  projectIndex: https://docs.falco-app.be/llms.txt
---

# Authentication & Security

### 🧱 Required headers

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

```http
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](https://dev.falco-app.be/en), 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