OAuth-koppeling voor softwareleveranciers

Naast de API-key ondersteunt de WOZ API OAuth 2.0 (authorization code met PKCE). Daarmee bouw je WOZ-waarden in je eigen software in, terwijl elke klant een eigen WozApi-account en eigen credits gebruikt. Voor jou als leverancier is de koppeling gratis. Het productverhaal en de aanvraag van client-credentials staan op woz-api.nl/woz-api-koppeling; deze pagina is de technische referentie.

Endpoints

Basis-URL: https://woz-api.nl. Alleen de authorization code flow met PKCE (S256) is toegestaan, met refresh tokens via de scope offline_access. Redirect-URI's matchen exact; https is verplicht, behalve op localhost voor ontwikkelwerk.

Scopes

Het access token bevat geen accountgegevens van de klant: geen e-mailadres, geen naam. Jouw software kent zijn eigen gebruiker al; van ons krijgt hij alleen data en saldo.

De flow, stap voor stap

# 1. Stuur de browser van je klant naar het authorize-endpoint
https://woz-api.nl/connect/authorize?client_id=JOUW_CLIENT_ID
  &response_type=code
  &redirect_uri=https://jouwsoftware.nl/wozapi/callback
  &scope=woz.lookup%20account.saldo%20offline_access
  &state=RANDOM_STATE
  &code_challenge=S256_CHALLENGE
  &code_challenge_method=S256
  &login_hint=klant@voorbeeld.nl
  &objecten=600

# 2. Na inloggen of registreren en toestemming komt de browser terug:
https://jouwsoftware.nl/wozapi/callback?code=DE_CODE&state=RANDOM_STATE

# 3. Wissel de code server-side in voor tokens
curl -X POST https://woz-api.nl/connect/token \
  -d grant_type=authorization_code \
  -d code=DE_CODE \
  -d redirect_uri=https://jouwsoftware.nl/wozapi/callback \
  -d client_id=JOUW_CLIENT_ID \
  -d client_secret=JOUW_CLIENT_SECRET \
  -d code_verifier=DE_PKCE_VERIFIER

# Antwoord:
# { "access_token": "...", "token_type": "Bearer", "expires_in": 3600,
#   "refresh_token": "...", "scope": "woz.lookup account.saldo offline_access" }

# 4. Vraag per object de WOZ-waarde op, op de credits van je klant
curl "https://woz-api.nl/Api/Adres?adres=Spuistraat%2036C,%201012TT%20Amsterdam" \
  -H "Authorization: Bearer ACCESS_TOKEN"

# 5. Ververs het access token wanneer het verlopen is (rotatie: je krijgt
#    ook een NIEUW refresh token terug; bewaar altijd het laatste)
curl -X POST https://woz-api.nl/connect/token \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN \
  -d client_id=JOUW_CLIENT_ID \
  -d client_secret=JOUW_CLIENT_SECRET

Onboarding-hints

Twee optionele parameters op de authorize-URL maken de onboarding voor je klant vrijwel frictieloos:

Registreren in de flow is passwordless: e-mailadres plus een code van 6 cijfers uit de mail, geen wachtwoord. Een nieuw account krijgt 10 gratis credits, dus de koppeling werkt direct, ook voordat er betaald is.

Tokens en levensduren

Saldo en foutafhandeling

• Elke geslaagde call geeft het resterende saldo van de klant terug in de header X-Credits-Remaining; los opvragen kan met GET /Api/Credits (scope account.saldo).
• 401: access token verlopen of ingetrokken. Ververs met het refresh token; faalt ook dat, laat de klant dan opnieuw koppelen.
• 402: het saldo van de klant is op. Toon een knop naar https://woz-api.nl/Account/Billing zodat de klant direct kan opwaarderen.
• 403 met code ApiCredentialBuitenApi: het token is buiten /Api/* gebruikt; access tokens zijn geen websessie.
• 403 over een ontbrekende scope: vraag de juiste scopes aan in de authorize-URL en laat de klant opnieuw koppelen.
• De klant kan de koppeling zelf verbreken (Account, Koppelingen op woz-api.nl); je tokens geven daarna 401. Behandel dat als "opnieuw koppelen nodig", niet als storing.

Zelf de kosten dragen?

Dat kan zonder OAuth: neem een gewoon WozApi-account met API-key en doe de calls server-side op eigen saldo. De OAuth-koppeling is bedoeld voor het model waarin jouw klanten zelf afrekenen bij WozApi.