TESTOMGEVING · API-documentatie
Sign inAuthenticatie met HVC API's
HVC API-aanroepen worden beveiligd met OAuth2 en JWT-validatie. Haal eerst een access token op via de HVC Authentication API en stuur dit mee bij je API-aanroepen. Inloggen op de developer portal is niet hetzelfde als authenticeren bij een API: deze portal is uitsluitend documentatie en genereert geen tokens.
1. Ontvang jouw integratiegegevens
Het HVC integratieteam levert de client_id, client_secret en de juiste scope voor jouw koppeling. Scope is verplicht. Gebruik de exact verstrekte waarde; verzin geen scope en laat deze niet leeg. Stem ook de omgeving en de benodigde API-toegang af met het integratieteam.
2. Vraag een token aan
Maak vanuit jouw applicatie of bijvoorbeeld Postman een POST-request naar het tokenendpoint van de juiste omgeving. Voor deze testomgeving is dat:
https://test-api.hvcgroep.nl/oauth2/v2.0/token
Kies in Postman Body → x-www-form-urlencoded. Gebruik Content-Type: application/x-www-form-urlencoded en stuur deze vier velden mee:
grant_type: client_credentials
client_id: de door het integratieteam verstrekte client-id
client_secret: het door het integratieteam verstrekte secret
scope: de door het integratieteam verstrekte scope (verplicht)
Gebruik geen JSON-body voor deze tokenaanvraag. Laat je HTTP-client de formulierwaarden coderen; plak secrets niet in een URL.
De succesvolle response bevat access_token, token_type en expires_in. token_type is Bearer; expires_in geeft de geldigheidsduur in seconden aan. De voorbeeldwaarde in de API-documentatie is geen garantie voor de geldigheidsduur van jouw token.
3. Gebruik het token bij API-aanroepen
Stuur de waarde van access_token mee in de Authorization-header van elke beveiligde API-aanroep, met het woord Bearer gevolgd door één spatie en het token:
Authorization: Bearer <access_token>
Gebruik hier het access token, niet je client-id of client-secret. JWT is het tokenformaat; een aanwezig token betekent niet automatisch dat je toegang hebt tot elke API. Gebruik de gegevens en token voor de afgesproken omgeving en koppeling.
4. Houd rekening met verlopen tokens
Hergebruik een geldig token binnen jouw integratie en vraag vóór het verlopen een nieuw token aan met dezelfde client-credentialsflow. Baseer dit op expires_in en houd een kleine veiligheidsmarge aan. Het client-secret blijft alleen nodig voor de tokenaanvraag en hoort niet in je gewone API-aanroepen.
Veelvoorkomende vragen en fouten
De tokenaanvraag mislukt. Controleer het endpoint, POST, de formuliercodering, grant_type en alle drie verstrekte waarden. Scope is verplicht. Raadpleeg de foutmelding zonder secrets of tokens te loggen.
De API geeft 401. Controleer of de Authorization-header aanwezig is, Bearer correct is geschreven en het token nog geldig is. Controleer ook of je de juiste omgeving gebruikt. De foutmelding en het integratieteam kunnen de exacte oorzaak bevestigen.
De API geeft 403 of toegang ontbreekt. Een token is geen garantie voor autorisatie. Laat het integratieteam de scope en toegang voor jouw koppeling controleren; de precieze betekenis hangt af van de betreffende API.
Kan ik een token of subscription key aanvragen in deze portal? Nee. Haal tokens op via de HVC Authentication API vanuit je eigen tools. Subscription keys kun je niet zelf aanvragen via deze portal; eventuele aanvullende toegangsafspraken lopen via het integratieteam.
Ga zorgvuldig om met credentials
Sla client-secrets en tokens op in geschikte geheime opslag. Neem ze niet op in broncode, gedeelde Postman-exports, screenshots, tickets of logs. Deel bij een ondersteuningsvraag alleen de API, omgeving, het tijdstip en een opgeschoonde foutmelding.