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.