De volgende stappen beschrijven hoe je de OAuth authorization flow gebruikt om een gebruiker jouw applicatie te laten autoriseren, en een access token te verkijgen waarmee je applicatie zich kan authenticeren als de gebruiker.

1. De gebruiker om toestemming vragen

Om gegevens van een Rompslomp gebruiker te kunnen uitlezen of aanpassen, moet de gebruiker jouw applicatie daar expliciet toestemming voor geven (autoriseren). Leid de gebruiker hiervoor naar de volgende locatie. Hier wordt de gebruiker gevraagd om uw applicatie al dan niet te autoriseren:

https://api.rompslomp.nl/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}

Toelichting bij plaatsvervangende aanduidingen:

{client_id}

Het client ID van jouw applicatie. Dit is een code bestaande uit een reeks willekeurige tekens die je van Rompslomp hebt gekregen.

{redirect_uri}

De locatie waar de gebruiker naartoe wordt geleid na de autorisatie. Deze locatie moet gelijk zijn aan de redirect uri die bij Rompslomp bekend is voor jouw applicatie.

{scope}

Hiermee geef je aan welke toegangsrechten (scopes) je applicatie nodig heeft. Het moet een door spaties geschieden lijst van scopes zijn. Vraag nooit meer scopes dan noodzakelijk is voor het functioneren van jouw integratie. Lees welke scopes er beschikbaar zijn bij Scopes. Optioneel. Default: 'public'.

2. Het verkrijgen van een access token

Na een succesvolle autorisatie wordt de gebruiker teruggeleid naar de redirect uri. Aan het request wordt middels een query parameter (code) een autorisatiecode toegevoegd:

https://jouwapp.example.org/rompslomp_callback?code=luDedp6KFum4b8NpoPgvcAw7hGx_oTEx9J68_nunPw0

Als de gebruiker je applicatie niet autoriseert dan wordt zij ook naar de redirect uri teruggeleid, maar wordt er geen autorisatiecode meegegeven. In plaats daarvan worden de query parameters error en error_description toegevoegd:

https://jouwapp.example.org/rompslomp_callback?error=access_denied&error_description=De+resource+eigenaar+of+autorisatie-server+weigerde+het+verzoek

De autorisatiecode kan (gedurende korte tijd) worden ingewisseld voor een access token. Met het access token kan je applicatie zich vervolgens bij de API authenticeren als de gebruiker. Voor het inwisselen van de autorisatiecode voor een access token gebruik je het OAuth token-endpoint als volgt:

curl --request POST 'https://api.rompslomp.nl/oauth/token' \
  --form 'client_id={client_id}' \
  --form 'client_secret={client_secret}' \
  --form 'grant_type=authorization_code' \
  --form 'code={code}' \
  --form 'redirect_uri={redirect_uri}'

Toelichting bij plaatsvervangende aanduidingen:

{client_id}

Het client ID van jouw applicatie.

{client_secret}

Het client secret wat je van Rompslomp gekregen hebt. Deze bestaat uit een reeks willekeurige tekens.

{code}

Gebruik de autorisatiecode die werd teruggegeven als de code parameter na autorisatie in stap 1.

{redirect_uri}

Gebruik de uri die werd gebruikt in stap 1.

Response

De response van het OAuth token-endpoint bevat een JSON object met daarin o.a. het access token.

// HTTP/1.1 200 OK

{
  "access_token": "LvpR0xfTE437L_sMufuZxYs1iASUn3b9OLLbPihUMGg",
  "token_type": "Bearer",
  "expires_in": 7199,
  "refresh_token": "WzZmMMCAsKmIH8QMq8dCTpxMyELIUn3-pfz1zHHPsIM",
  "scope": "public",
  "created_at": 989532000
}

Een typische OAuth client bewaart het access token en het refresh token als attributen van de betreffende gebruiker, zodat de gebruiker slechts éénmaal toestemming hoeft te geven.

Als de autorisatiecode niet ingewisseld kan worden, bijvoorbeeld omdat deze verlopen is, dan ziet de response er als volgt uit:

// HTTP/1.1 400 Bad Request
// WWW-Authenticate: Bearer realm="Rompslomp API v1", error="invalid_grant", error_description="De verstrekte autorisatie is ongeldig, verlopen, ingetrokken, komt niet overeen met de redirect uri die is opgegeven, of werd uitgegeven aan een andere klant."

{
  "error": "invalid_grant",
  "error_description": "De verstrekte autorisatie is ongeldig, verlopen, ingetrokken, komt niet overeen met de redirect uri die is opgegeven, of werd uitgegeven aan een andere klant."
}

(Niet-relevante headers zijn weggelaten.)

Alle informatie over het OAuth token-endpoint vind je op de API endpoints pagina.

Authenticatie

Het access token kan worden gebruikt om API requests te doen uit naam van de gebruiker.

Geef het access token op deze manier mee in de Authorization header wanneer je een request doet naar de Rompslomp API: "Bearer {API_TOKEN}".

Voorbeeld gebruik Authorization header

curl --request GET 'https://api.rompslomp.nl/api/v1/companies/54321/sales_invoices' \
  --header 'Authorization: Bearer LvpR0xfTE437L_sMufuZxYs1iASUn3b9OLLbPihUMGg'