Autorisatie
Voogd & Voogd maakt gebruik van het Bearer authentication scheme, ook wel token authentication genoemd. Dit betekent dat elke API call naar een endpoint van de REST API voorzien moet zijn van een additionele authentication header. Op basis van deze header kan Voogd & Voogd het verzoek herkennen en op gepaste wijze afhandelen.
Authorization: Bearer <token>
Let op: De gegenereerde access tokens hebben een verloopdatum, standaard staat deze op één uur. Het is dan ook belangrijk dat uw applicatie hierop is afgestemd en het access tokens tijdig vernieuwt om een correcte werking van uw applicatie te kunnen garanderen.
REST API
Token genereren
Na het generen van een Consumer Key / Secret combinatie is het mogelijk om via de REST API een access token te genereren. Hiervoor dient consumer-key:consumer-secret
middels een base64 hashing
meegegeven te worden.
curl -k -d "grant_type=password&username=Username&password=Password" \
-H "Authorization: Basic Base64(consumer-key:consumer-secret)" \
https://api.voogd.com/token
Voorbeeld response:
{
"access_token" : "xxxx-xxx-xxx-xxx",
"refresh_token" : "yyyy-yyy-yyy-yyy",
"scope" : "default",
"token_type" : "Bearer",
"expires_in" : 3600
}
Token vernieuwen
De aangemaakte tokens hebben een expiratietijd van één uur. Na het verlopen van het token worden verdere API requests geweigerd op basis van autorisatie. Het is daarom belangrijk om het token tijdig te vernieuwen voordat het attribuut expires_in
de 0 passeert.
Bij het vernieuwen wordt een nieuw access_token
en refresh_token
geretourneerd; de originele access_tokens
en refresh_token
zijn daarmee direct verlopen.
curl -k -d "grant_type=refresh_token&refresh_token=xxxx-xxx-xxx-xxx" \
-H "Authorization: Basic Base64(consumer-key:consumer-secret) " \
https://api.voogd.com/token
Voorbeeld response:
{
"access_token" : "xxxx-xxx-xxx-xxx",
"refresh_token" : "yyyy-yyy-yyy-yyy",
"scope" : "default",
"token_type" : "Bearer",
"expires_in" : 3600
}
API Devportal
Het is mogelijk om tijdelijke tokens via de API Devportal te genereren, dit kan handig zijn indien u bijvoorbeeld iets wilt testen of handmatig wilt controleren. Onder het tabje Applications kunt u de gewenste modus selecteren ( productie vs sandbox ) en vanaf daar de access token genereren.
Let op: omdat de tokens verlopen adviseren wij u om de tokens nooit voor productiedoeleinden te hanteren.