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

• API-sleutels

• OAuth 2.0

• Basic authentication (niet langer aanbevolen)

API-sleutel

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.

Een API-sleutel van een boekhoudersportaal kan ook toegang krijgen tot accounts onder het portaal. Gebruik header X-AccountId om mee te geven welke account je toegang tot wenst.

OAuth 2.0

Naast API-sleutels is er ook ondersteuning voor OAuth.
Dit is vooral bedoeld voor toepassingen die toegang nodig hebben tot API’s namens een gebruiker, zonder dat wachtwoorden of API-sleutels gedeeld moeten worden.

Meer informatie over het gebruik van OAuth vind je op de pagina: OAuth authenticatie

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"]
}