Met OAuth 2.0 kan een externe toepassing veilig toegang krijgen tot de API namens een gebruiker, zonder dat wachtwoorden of API-sleutels gedeeld hoeven te worden.

OAuth is vooral bedoeld voor integraties die door gebruikers zelf geautoriseerd worden — bijvoorbeeld koppelingen met externe applicaties, plugins of mobiele apps.

Een koppeling met OAuth is steeds beperkt tot 1 account. Tijdens de autorisatie zal de gebruiker een selectie maken van de account indien de gebruiker toegang heeft tot meerdere accounts.

Wens je enkel eenvoudig toegang tot je eigen account? Dan raden we het gebruik van een API-sleutel aan. De implementatie met een API-sleutel is namelijk eenvoudiger.

Registratie applicatie

Om gebruik te kunnen maken van OAuth moet je applicatie worden geregistreerd. Contacteer de helpdesk om je applicatie te registreren.

Volgende gegevens moet je doorgeven:

1. Naam van de applicatie
2. Eén of meerdere redirect url's
3. Korte uitleg waarvoor je OAuth binnen je applicatie wenst te gebruiken

Na registratie ontvang je een client_id en client_secret.

Overzicht van het proces

De OAuth 2.0-implementatie volgt de standaard Authorization Code Flow.

Het proces verloopt in drie stappen:

1. Gebruiker autoriseert de toepassing
   De gebruiker wordt doorgestuurd naar de autorisatiepagina.
   Daar logt hij in en geeft toestemming voor toegang tot zijn account.

2. Applicatie ontvangt een autorisatiecode
   Na goedkeuring wordt de gebruiker teruggestuurd naar de redirect_uri van de toepassing, met een tijdelijke autorisatiecode.

3. Applicatie wisselt de code in voor een access token
   De toepassing vraagt een access token aan via het token-endpoint.
   Dit token gebruik je vervolgens om geauthenticeerde API-aanroepen uit te voeren.

Endpoints

Voorbeeld: Authorization Code Flow

1. Gebruiker autoriseren

Stuur de gebruiker naar de volgende URL:

https://eenvoudigfactureren.be/oauth/authorize

met de volgende queryparameters:

Voorbeeld-URL:

https://eenvoudigfactureren.be/oauth/authorize?client_id=abcd1234&redirect_uri=https://example.com/callback&response_type=code&scope=invoices%20clients&state=xyz123&prompt=login

2. Access token aanvragen

Wanneer de gebruiker de toegang goedkeurt, wordt hij teruggestuurd naar:

https://example.com/callback?code=AUTH_CODE&state=xyz123

Gebruik vervolgens deze autorisatiecode om een token aan te vragen:

POST /oauth/token

Body:

grant_type=authorization_code
client_id=abcd1234
client_secret=dcba4321
redirect_uri=https://example.com/callback
code=AUTH_CODE

Voorbeeld response:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8"
}

3. API-aanroepen uitvoeren

Gebruik het ontvangen access token bij elke API-aanroep via de HTTP-header:

Authorization: Bearer eyJhbGciOi...

Tokens vernieuwen

Access tokens hebben een beperkte geldigheidsduur (standaard 1 uur).
Gebruik het refresh_token om een nieuw access token aan te vragen zonder opnieuw te moeten inloggen.

POST /oauth/token

Body:

grant_type=refresh_token
refresh_token=8xLOxBtZp8
client_id=abcd1234
client_secret=dcba4321

Scopes

Scopes bepalen tot welke onderdelen van de API de toepassing toegang heeft.

Beschikbare scopes:

Bijkomend moet de gebruiker ook over de nodige rechten te beschikken om binnen een scope te kunnen werken. Dit wordt niet afgedwongen dit het uitvoeren van de OAuth flow.

Veiligheidstips

• Gebruik altijd HTTPS voor alle OAuth-verzoeken.

• Bewaar refresh tokens op een veilige manier, bij voorkeur op de server.

• Vraag enkel de scopes die je nodig hebt.