Access to the API is done via HTTP authentication, based on the REST principle. Two methods are available:

  • API keys (recommended)

  • Basic authentication (no longer recommended)


API Key (recommended)

The preferred method of authentication is using an API key.

  • Each account can create one or more API keys via the Access Management menu.

  • An API key grants access to a specific account.

Use the following HTTP header to include an API key in an API request:

  • X-API-Key: your_api_key

Tip: Treat API keys as sensitive data. Use them only in secure environments.


An API key from an accountant portal can also access accounts under the portal. Use the header X-AccountId to specify which account you want to access.


Basic authentication (deprecated)

Basic authentication is still supported, but no longer recommended due to lower security.

With this method, you provide the user's email address and password via the Authorization header:

  • Authorization: Basic base64encode("email:password")

Example: The value Basic amFuQGRvbWFpbi5iZTpNaW5OaWV0QVBJIQ== is the Base64 version of jan@domain.be:MijnWachtwoord.


Note: Use this method only in exceptional cases, such as when generating a new API key (see below).


Working with multiple accounts

If a user has access to multiple accounts, you can specify the desired account using the following header:

  • X-AccountId: CAAAAAAAA

Note:

  • CAAAAAAAA is the account number.

  • You can find the account number on the account page (settings menu in the top right).

  • If this header is not specified, the user's main account is used by default. You can set this via the user settings.


Create a new API key via the API

You can also create API keys via the API.

Use a POST request to: /api/v1/apikeys


This requires authentication via basic authentication. The request must include at least the following data:

  • name (required): the name of the key.

  • rights (optional): list of access rights. If not provided, the key will receive full access by default.


Example body:

{
  "name": "Integration with webshop",
  "rights": ["invoices", "clients"]
}


Recommended approach:
Create API keys via the EenvoudigFactureren interface where possible, and limit the use of basic authentication to key management in exceptional situations.



  Want to know more about the API? Check the useful articles below