> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate your API requests with the API key of your company as a Bearer token.

## Overview

The e-invoice.be API uses Bearer token authentication. Each [company](/glossary#company) has its own API key. Send the key in the `Authorization` header of each request to `https://api.e-invoice.be`.

The API key identifies the company. Thus the key also controls if a send goes to the Peppol network ([production company](/glossary#production-company)) or to email ([sandbox company](/glossary#sandbox-company)).

<Note>
  Develop and test with a sandbox company. A sandbox company runs in test mode: the API sends each document as UBL XML to the contact email address of the company, and nothing goes to the Peppol network. The API host and the endpoints are the same as for a production company. See [Test mode and sandbox companies](/environments).
</Note>

## Get your API key

<Steps>
  <Step title="Sign in">
    Sign in to [app.e-invoice.be](https://app.e-invoice.be).
  </Step>

  <Step title="Select the company">
    Select the company that you want to use. A sandbox company and a production company have different keys.
  </Step>

  <Step title="Copy the key">
    Open **API Settings** and copy the API key.
  </Step>
</Steps>

<Warning>
  Keep your API key secret. Do not put it in version control, in client-side code or in a public location.
</Warning>

## Make an authenticated request

Add the header `Authorization: Bearer <your API key>` to the request. The samples read the key from the environment variable `E_INVOICE_API_KEY` and call `GET /api/me/`, which returns the data of the company that owns the key.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.e-invoice.be/api/me/" \
    -H "Authorization: Bearer $E_INVOICE_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.e-invoice.be/api/me/", {
    headers: { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` },
  });

  const result = await response.json();
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
  }
  console.log(result);
  ```

  ```python Python theme={null}
  import os

  import requests

  response = requests.get(
      "https://api.e-invoice.be/api/me/",
      headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
      timeout=30,
  )
  if not response.ok:
      raise SystemExit(f"HTTP {response.status_code}: {response.text}")
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.e-invoice.be/api/me/");
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer " . getenv("E_INVOICE_API_KEY"),
      ],
  ]);

  $body = curl_exec($ch);
  $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($status >= 400) {
      throw new RuntimeException("HTTP $status: $body");
  }
  print_r(json_decode($body, true));
  ```

  ```csharp C# theme={null}
  using System.Net.Http.Headers;

  using var client = new HttpClient { BaseAddress = new Uri("https://api.e-invoice.be") };
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
      "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

  var response = await client.GetAsync("/api/me/");

  var body = await response.Content.ReadAsStringAsync();
  if (!response.IsSuccessStatusCode)
  {
      throw new HttpRequestException($"HTTP {(int)response.StatusCode}: {body}");
  }
  Console.WriteLine(body);
  ```
</CodeGroup>

A correct key gives a `200` response:

```json theme={null}
{
  "name": "E-INVOICE BV",
  "description": null,
  "plan": "starter",
  "credit_balance": 100,
  "peppol_ids": ["0208:1018265814"],
  "ibans": null,
  "company_number": "1018265814",
  "company_tax_id": "BE1018265814",
  "company_name": "E-INVOICE BV",
  "company_address": "Brusselsesteenweg 119/A",
  "company_zip": "1980",
  "company_city": "Zemst",
  "company_country": "Belgium",
  "company_email": "billing@e-invoice.be",
  "smp_registration": true,
  "smp_registration_date": "2025-01-15T10:30:00Z",
  "bcc_recipient_email": null
}
```

The response also contains the plan and the credit balance. See [Usage statistics and credits](/guides/usage-statistics).

## Endpoints without authentication

Three read-only Peppol lookup operations do not require an API key: `GET /api/validate/peppol-id`, `GET /api/lookup` and `GET /api/lookup/participants`. All other operations require the `Authorization` header.

## Best practices

### Keep the key in an environment variable

Do not write the key in your source code. Read it from an environment variable or from a secret manager.

```bash theme={null}
# .env (add this file to .gitignore)
E_INVOICE_API_KEY=your_api_key
E_INVOICE_BASE_URL=https://api.e-invoice.be
```

### Use a different key for tests and for production

Use the key of a sandbox company in your development and test systems. Use the key of a production company only in your production system. The base URL and your code are the same for the two.

### Reset a key that is no longer safe

If a key is possibly known to other persons, open **API Settings** in the app and select **Reset API key**. The app creates a new key and the previous key stops working. Then update your applications with the new key.

## Error responses

A request with no valid key returns `401 Unauthorized` with the header `WWW-Authenticate: Bearer`.

If the `Authorization` header is missing:

```json theme={null}
{
  "detail": "Authentication required"
}
```

If the key is not correct or is deleted:

```json theme={null}
{
  "detail": "Invalid authentication"
}
```

### Troubleshooting

<Steps>
  <Step title="Examine the header format">
    The header value must be `Bearer`, one space, then the key.
  </Step>

  <Step title="Remove spaces">
    Make sure that the key has no spaces or line breaks before or after it.
  </Step>

  <Step title="Make sure that the key is from the correct company">
    A sandbox company and a production company have different keys. A key that was reset in the app does not work.
  </Step>

  <Step title="Test with cURL">
    Call `GET /api/me/` with the `-v` option and read the response status.

    ```bash theme={null}
    curl -v "https://api.e-invoice.be/api/me/" \
      -H "Authorization: Bearer $E_INVOICE_API_KEY"
    ```
  </Step>
</Steps>

For all status codes and error formats, see [Errors and troubleshooting](/guides/errors).

## Next Steps

<CardGroup cols={2}>
  <Card title="Test mode and sandbox companies" icon="flask" href="/environments">
    Create a sandbox company and learn what test mode does.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API call.
  </Card>

  <Card title="Create e-invoices" icon="file-invoice" href="/guides/creating-invoices">
    Create and send an e-invoice.
  </Card>

  <Card title="Validation during development" icon="circle-check" href="/guides/validation">
    Validate invoice payloads during development.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.