Intro Releasenotes Documentatie & testen ClientID Access Token Webhooks Postman Best practices Unauthorized(401) Forbidden(403) Limiet Bereikt (429) Meldingen FAQ Terminologie Use case: bijwerken persoon Use case: niet beschikbaarheid Use case: aanbod op website Use case: inschrijving versturen Datamodel
| Wanneer je gaat werken met de API, dan maak je gebruik van access tokens. Een access token zorgt ervoor dat je toegang krijgt tot een API. Wil je gegevens van een toepassing ophalen door gebruik te maken van een API, dan dien je jezelf te authentiseren. Dat betekent dat je een gebruiker en wachtwoord ingeeft. Op basis van die informatie wordt gekeken of je de juiste rechten hebt. Heb je de juiste rechten, dan ontvang je een access token. Geef je bij het ophalen van de informatie dit token mee, dan weet de toepassing dat je geautoriseerd bent. Heb je na het lezen van dit document nog vragen of advies nodig, aarzel dan niet en neem contact met ons op. Wij geven jullie graag advies! |
| Wanneer heb je een token nodig? |
| Bij elke aanroep die je naar een API doet dien je een geldig token te hebben. Heb je geen geldig token, dan ben je niet geautoriseerd (status 401 Unauthorized) en ontvang je dus geen data via de API. Daarnaast kun je ook geen data naar de API sturen zonder geldig token. |
| Wat is de levensduur van een token? |
| Er is geen vaste levensduur voor een token. Per toepassing kan bepaald worden wat de maximale levensduur mag zijn van een token. Voor Coachview geldt dat dit 15 minuten, 1 uur of 8 uur is. Ons advies is om een token zo kort mogelijk geldig te laten zijn. |
| Wanneer vraag ik een nieuw token aan? |
| Een nieuw token hoeft je pas aan te vragen wanneer het vorige token bijna of helemaal verlopen is. Een token is een sleutel waarmee je toegang hebt tot de data van Coachview. Hoe meer sleutels er uitgegeven zijn hoe meer mogelijkheden er zijn om bij de data te kunnen. Doordat je de levensduur kort houdt voorkom je ongewenste toegang tot de data. |
| Is het verstandig om een token zo lang mogelijk in te stellen? |
| Nee, dat is niet verstandig. Zo lang het token geldig is, heeft degene die dat token bezit, toegang tot de API van de betreffende toepassing. Stel je vraagt om 13:00 uur een token aan die 8 uur geldig is, dan kan iemand die in het bezit is van dat token tot 21:00 uur data ophalen en versturen naar de betreffende toepassing. Is de levensduur slechts 15 minuten, dan kan vanaf 13:16 uur dit token niet meer gebruikt worden. |
| Wat gebeurt er als ik elke 15 minuten een API call wil doen en de lifetime (levensduur) op 8 uur zet? |
| Wanneer je elke 15 minuten een token aanvraagt die 8 uur geldig is, dan betekent dit dat je veel meer access tokens hebt waarmee je toegang kunt krijgen tot de API. Na 1 uur heb je 4 tokens, na 2 uur 8 tokens en na 8 uur 32 tokens. Het gevolg is dat je na deze 8 uur 32 verschillende tokens kunt gebruiken om data op te halen van en te versturen naar de betreffende toepassing. Hiermee loop je dus een groter risico dan wanneer je elke 15 minuten een token opvraagt. |
| Kan ik zien hoelang een token nog geldig is? |
| Jazeker, nadat je een API call gedaan hebt krijg je in de response (reactie) tot welk tijdstip het gebruikte token geldig is. { "access_token":"123......", "token_type":"Bearer", "expires_in":3600 } Voor meer informatie zie https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/ |
| Gebruik het verversen van access tokens efficiënt! |
| Wanneer jouw access token over 10 minuten vervalt, dan dien je de refresh token te gebruiken om een nieuwe access token aan te vragen. Wanneer je een nieuwe access token aanvraagt, dan zie je in de response hoe lang de token nog geldig is (zie voorbeeld hierboven). Om dit zo efficiënt mogelijk te organiseren dien je met twee zaken rekening te houden. 1. Vraag een access token niet te laat aan. Gebruik jouw refresh token voor het aanvragen van een nieuwe access token voordat deze vervalt. Wanneer je een API-call uitvoert met een vervallen access token, dan wordt jouw call afgekeurd met error code 401 met als reden "Authenticatie verplicht". 2. Vraag een token niet te vroeg aan. Je dient alleen een nieuw token aan te vragen net voordat de andere vervalt. Op dit moment hebben wij hier nog geen limiet op staan, maar het zou bijvoorbeeld verstandig zijn om geen nieuw token aan te vragen wanneer het andere token nog meer dan 30 seconde geldig is. Vraag niet voor elke API-call een nieuw access token aan. Zeker wanneer je meerdere calls direct achter elkaar doet, dan is dit niet verstandig. Het beste kun je ervoor zorgen dat je bij iedere API-call controleert hoelang en of het oude access token nog geldig is en alleen een nieuwe aanvraagt als de oude bijna verloopt of verlopen is. |
| Hoe vraag ik een token aan? |
| Het betreft de oauth2 flow. Deze dient strict gevolgd te worden. Zie https://www.rfc-editor.org/rfc/rfc6749 voor meer informatie. Hieronder de belangrijke stappen: 1. POST https://secure.coachview.net/connect/token. Hiervoor dient de header "Content-Type = application/x-www-form-urlencoded" te zijn. Stuur je een andere content type mee dan krijg je statuscode 400 met de melding: { "error": "invalid_request" } 2. Body In de body dient onderstaande informatie te staan: client_id={clientid}&client_secret=clientsecret}&grant_type=client_credentials&scope={scope}
- {clientid} = het clientid dat is aangemaakt en terug te vinden via /auth/settings - {clientsecret} = het opgegeven secret bij het aanmaken van de client via /auth/settings - {scopes} = Altijd starten met ‘api ’ en daarnaast de scopes die zijn aangevinkt via /auth/settings Voorbeeld client_id=xxx-xx-xxx-xxx-xxxx&client_secret=Cl1entS3creT&grant_type=client_credentials&scopes=api Opleidingen.Lezen Opleidingssoorten.Lezen LET OP: Alles moet op 1 regel als 1 lange string meegestuurd worden. Anders krijg je een status 400 met de melding { "error": "invalid_client" } |
Bijgewerkt tot en met versie 85
