Toegang tot de API gebeurt via HTTP-authenticatie, op basis van het REST-principe. Er zijn twee methodes beschikbaar:

  • API-sleutels (aanbevolen)

  • Basic authentication (niet langer aanbevolen)


API-sleutel (aanbevolen)

De voorkeursmethode voor authenticatie is het gebruik van een API-sleutel.

  • Per account kunnen één of meerdere API-sleutels worden aangemaakt via het menu Toegangsbeheer.

  • Een API-sleutel verleent toegang tot één specifieke account.

Gebruik de volgende HTTP-header om een API-sleutel mee te geven bij een API-aanvraag:

  • X-API-Key: je_api_sleutel

Tip: Behandel API-sleutels als gevoelige gegevens. Gebruik ze enkel in beveiligde omgevingen.


Basic authentication (verouderd)

Basic authentication is nog ondersteund, maar wordt niet langer aanbevolen wegens minder veilig.

Bij deze methode geef je het e-mailadres en wachtwoord van een gebruiker door via de Authorization-header:

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

Voorbeeld: De waarde Basic amFuQGRvbWFpbi5iZTpNaW5OaWV0QVBJIQ== is de Base64-versie van jan@domain.be:MijnWachtwoord.


Let op: Gebruik deze methode enkel in uitzonderlijke gevallen, bijvoorbeeld wanneer je een nieuwe API-sleutel wil genereren (zie verder).


Werken met meerdere accounts

Indien een gebruiker toegang heeft tot meerdere accounts, kan je het gewenste account specificeren via de volgende header:

  • X-AccountId: CAAAAAAAA

Merk op:

  • CAAAAAAAA is het accountnummer.

  • Je vindt het accountnummer op de account-pagina (instellingenmenu rechtsboven).

  • Indien deze header niet wordt opgegeven, wordt standaard het hoofdaccount van de gebruiker gebruikt. Je kan dit instellen via de gebruikersinstellingen.


Nieuwe API-sleutel aanmaken via de API

Je kan ook API-sleutels aanmaken via de API.

Gebruik hiervoor een POST-verzoek naar: /api/v1/apikeys


Dit vereist authenticatie via basic authentication. In het verzoek geef je minimaal volgende gegevens mee:

  • name (verplicht): de naam van de sleutel.

  • rights (optioneel): lijst van toegangsrechten. Indien niet opgegeven, krijgt de sleutel standaard volledige toegang.


Voorbeeld body:

{
  "name": "Integratie met webshop",
  "rights": ["invoices", "clients"]
}


Aanbevolen werkwijze:
Maak een API-sleutel aan via de interface van EenvoudigFactureren waar mogelijk, en beperk het gebruik van basic authentication tot sleutelbeheer in uitzonderlijke situaties.



  Meer info over de API? Lees onderstaande nuttige artikels