Skip to Content

API's

Bescherm uw API's als OAuth-resources: definieer scopes, beheer machine-to-machine- en gebruikerstoegang en stel tokenformaat en levensduur in.

Een API vertegenwoordigt een beschermde resource waarvoor applicaties access tokens verkrijgen. Door een API te registreren vertelt u het platform wat de identifier van de resource is (de audience), welke scopes (machtigingen) deze aanbiedt, welke applicaties deze mogen aanroepen en hoe de uitgegeven access tokens zijn opgebouwd en ondertekend.

U beheert API's onder Integraties → API's in de Admin Console.

Wat een API is

Elke API heeft:

  • een naam, een label voor beheerders, en
  • een identifier, de audience-waarde die verschijnt in tokens die voor deze API worden uitgegeven (bijvoorbeeld https://api.example.com).

Bij een custom API kunt u ook contactpersonen opgeven: de medewerkers bij wie u met vragen over de API terechtkunt. Dit is puur informatief en geeft hun geen rechten.

Er zijn twee soorten:

  • System API: de eigen management-API van het platform. De naam, identifier en scopes liggen vast en kunnen niet worden bewerkt.
  • Custom API: een API die u registreert en beheert: u definieert de scopes, wie deze mag aanroepen en de tokeninstellingen.

Scopes (machtigingen)

Een scope is één machtiging die een token kan bevatten, bijvoorbeeld read:documents of orders.write.

  • De System API biedt een vaste catalogus van managementscopes (bijvoorbeeld users.read, users.write, groups.read, roles.write, logs.read). Dit zijn de scopes die u verleent aan applicaties die de eigen management-API van het platform aanroepen.
  • Een custom API biedt de scopes die u definieert. Voeg op het tabblad met machtigingen van de API elke scope toe met een naam en een beschrijving. Enkele gereserveerde OpenID Connect-scopes (zoals openid, profile, email, offline_access) kunnen niet opnieuw worden gedefinieerd.

Sommige managementscopes staan bewust naast hun basisscope, in plaats van daarin besloten te liggen. De belangrijkste is users.mfa.read, die de MFA-registraties van een gebruiker omvat (welke tweede factoren zijn geregistreerd en wanneer elke factor voor het laatst is gebruikt). Deze scope is vereist op elk endpoint dat een gebruiker retourneert, inclusief de antwoorden van aanmaken, bijwerken, verwijderen en de aanroepen voor deactiveren en activeren. Een token met alleen users.read of users.write ontvangt de gebruiker zonder de lijst met registraties, dus verleen users.mfa.read aanvullend wanneer een integratie die nodig heeft.

Wie een API mag aanroepen

Twee onafhankelijke beleidsregels beheren de toegang, één voor elk soort aanroeper:

Gedelegeerde gebruikerstoegang

Wanneer een interactieve applicatie een token aanvraagt namens een aangemelde gebruiker, bepaalt het gebruikersbeleid van de API of dit is toegestaan:

  • Alle applicaties toestaan: elke interactieve applicatie mag tokens voor deze API aanvragen.
  • Autorisatie per app vereisen: alleen applicaties die u uitdrukkelijk hebt geautoriseerd, mogen tokens aanvragen, en alleen voor de scopes die u hun verleent.
  • Alle applicaties weigeren: geen enkele interactieve applicatie mag tokens aanvragen.

Machine-to-machine-toegang

Wanneer een applicatie zich als zichzelf authenticeert met de client-credentials-grant (zonder gebruiker), bepaalt het clientbeleid van de API of dit is toegestaan:

  • Autorisatie per app vereisen: alleen applicaties die u uitdrukkelijk hebt geautoriseerd, mogen tokens aanvragen, beperkt tot de verleende scopes.
  • Alle applicaties weigeren: geen enkele machine-to-machine-applicatie mag tokens aanvragen.

Een applicatie autoriseren

Waar een beleid op Autorisatie per app vereisen staat, autoriseert u een applicatie via het tabblad Applicatietoegang van de API:

  1. Kies Applicatie toevoegen in de sectie voor gedelegeerde gebruikerstoegang of voor de client (machine-to-machine).
  2. Selecteer de applicatie.
  3. Selecteer de scopes die u wilt verlenen, of kies Altijd alle machtigingen verlenen om huidige en toekomstige scopes automatisch op te nemen.
  4. Sla op. Tokens die het platform voor deze API aan die applicatie uitgeeft, bevatten nu de verleende scopes.

Een machine-to-machine-applicatie is doorgaans van het applicatietype machine-to-machine; zie Applicaties.

De API-lijst in de Admin Console

Een API-token testen

Zodra voor een API ten minste één machine-to-machine-applicatie is geautoriseerd (met de client-credentials-grant), kunt u via het tabblad Test van de API een token van begin tot eind uitproberen zonder code te schrijven:

  1. Selecteer een van de geautoriseerde machine-to-machine-applicaties.
  2. De pagina toont een direct uitvoerbaar voorbeeld van een tokenaanvraag aan het token-endpoint, met de client-ID en het secret van die applicatie en de identifier van deze API als audience.
  3. De pagina toont het tokenantwoord en decodeert het uitgegeven access token in header, payload en signature, zodat u kunt controleren of de audience en de verleende scopes zijn wat u verwacht.
  4. De pagina toont een voorbeeld van een API-aanroep die het token als Bearer-header verzendt.

Kopieer de opdrachten om ze in uw eigen terminal uit te voeren. Als het tabblad Test aangeeft dat u eerst een applicatie moet autoriseren, verleen dan een machine-to-machine-applicatie toegang op het tabblad Applicatietoegang en laad de pagina opnieuw.

Resource indicators en tokens

Elk access token dat het platform voor een API uitgeeft, bevat de identifier van die API als audience, zodat de resource kan controleren of het token voor haar bedoeld was. Applicaties kiezen met de resource indicator voor welke API zij een token willen, waardoor één applicatie afzonderlijke tokens met een eigen audience voor meerdere API's kan hebben.

Op het tabblad met instellingen van de API bepaalt u hoe die tokens zijn opgebouwd:

  • Ondertekeningsalgoritme: het asymmetrische algoritme (RS256, RS384, RS512 of PS256) waarmee de tokens worden ondertekend. Kies PS256 voor een API die wordt aangeroepen door een applicatie met een Financial-grade API-beveiligingsprofiel: dat profiel ondertekent de eigen tokens van de applicatie met PS256 en raadt RS256 af. Deze instelling staat los van het profiel en moet daarom ook hier worden gewijzigd.
  • Access token lifetime: hoe lang een token geldig is (standaard één dag).
  • Implicit access token lifetime: een kortere levensduur voor tokens die via browsergebaseerde implicit flows worden uitgegeven (standaard twee uur).

Eén API of meerdere?

Een access token bevat altijd precies één audience. Tokens met meerdere audiences worden niet uitgegeven: een token dat voor de ene API is aangemaakt, wordt door een andere niet geaccepteerd (zie De API als verifieerbaar contract). Als uw backend uit een reeks microservices bestaat, moet u daarom een ontwerpkeuze maken:

Eén logische API voor één vertrouwensdomein. Registreer één API waarvan de identifier voor de hele backend staat (bijvoorbeeld https://api.example.com) en geef elke service een eigen scope-namespace (orders.read, inventory.write enzovoort). Elke service valideert dezelfde audience en dwingt alleen haar eigen scopes af; de client heeft één token voor de hele backend, en een nieuwe service sluit aan door scopes toe te voegen in plaats van een nieuwe registratie. Kies dit wanneer de services samen worden gebouwd en beheerd, doorgaans achter één gateway. Houd rekening met de keerzijde: binnen de gedeelde audience isoleren de services elkaar niet meer via de audiencecontrole (elke service accepteert een token dat naar een zusterservice is gestuurd), alleen nog via scopes.

Eén API per vertrouwensgrens. Registreer afzonderlijke API's wanneer de resources verschillende vertrouwensniveaus of eigenaren hebben, of wanneer derden betrokken zijn. Een client vraagt dan via de resource indicator een afzonderlijk token per API aan (zie Resource indicators en tokens), en een backendservice kan een token dat zij al heeft omwisselen via token exchange. Over de grens heen blijft de audiencecontrole zinvol: een token dat bij de ene API wordt onderschept, is bij de andere waardeloos.

Een combinatie van beide is gebruikelijk: één logische API voor de samenhangende kern, afzonderlijke API's voor de delen die sterkere isolatie nodig hebben.

Hoe ver u het token van een gebruiker doorgeeft. Behandel het access token van de gebruiker als een credential, niet als verzoekcontext. Geef het hoogstens één stap door, van de client naar de rand van uw API (de gateway of de eerste service). Services dieper in een aanroepketen moeten ofwel achter de gedeelde audience van de logische API staan, ofwel een smaller token ontvangen dat via token exchange is aangemaakt; elke extra stap die het oorspronkelijke token aflegt, vergroot het gebied waarin een gelekt token kan worden hergebruikt.

Token exchange

Het token-endpoint ondersteunt OAuth 2.0 Token Exchange (RFC 8693), zodat een service namens een aangemelde gebruiker een downstream-API kan aanroepen zonder het oorspronkelijke token door te geven: de applicatie wisselt een access token van een gebruiker dat zij al heeft om voor een nieuw, smaller token voor een andere API.

De grant is bewust beperkt tot downscoping:

  • Alleen een web-applicatie (confidential) kan deze gebruiken, en alleen wanneer Token exchange bij de grant types is ingeschakeld (zie Applicaties).
  • Het subject token moet een nog geldig access token van een gebruiker zijn dat is uitgegeven aan dezelfde applicatie die de uitwisseling uitvoert. Het uitwisselen van tokens van een andere applicatie, tokens zonder gebruiker of delegatie met een actor_token wordt niet ondersteund.
  • De aanvraag noemt via resource precies één doel-API. Het beleid voor gedelegeerde gebruikerstoegang van de doel-API geldt voor de uitwisselende applicatie zoals bij elke andere tokenaanvraag.
  • Het uitgegeven token is nooit ruimer dan het subject token: de scopes zijn de doorsnede van de aangevraagde scopes, de scopes van het subject token, de scopes van de doel-API en waar de gebruiker recht op heeft.
  • Het nieuwe token blijft gebonden aan dezelfde gebruiker en sessie en volgt de instellingen voor tokenlevensduur van de doel-API.

Voorbeeldaanvraag aan het token-endpoint (de applicatie authenticeert zich zoals gebruikelijk, bijvoorbeeld met haar client secret):

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.read

Het antwoord bevat het nieuwe access_token samen met expires_in en de daadwerkelijk verleende scope.

Scopes vs. machtigingen

Het definiëren van een scope op een API maakt deze alleen aanvraagbaar; het verleent niemand toegang. Wat daadwerkelijk in een token terechtkomt, wordt apart bepaald:

  • Voor machine-to-machine-tokens bevat het token precies de scopes die de clientautorisatie van de applicatie toestaat (zie Een applicatie autoriseren). Een machineclient heeft geen gebruiker en geen rollen, dus het toewijzen van een rol aan een machine-to-machine-applicatie heeft geen effect; de scopes komen alleen uit de autorisatie.
  • Voor tokens met een gebruiker (uitgegeven wanneer een interactieve app namens een aangemelde gebruiker een token aanvraagt) bepaalt rolgebaseerd toegangsbeheer op welke scopes de gebruiker recht heeft. De scopes die in het token terechtkomen, zijn de doorsnede van wat de applicatie heeft aangevraagd en waar de gebruiker recht op heeft.

Dit is het gebruikelijke antwoord op de vraag "waarom ontbreekt de scope die ik heb aangevraagd zonder melding in mijn token?": de scope is aangevraagd, maar de aanroeper had er geen recht op, dus is deze weggelaten in plaats van geweigerd.

Defense in depth: een scope in een token is een verlening, geen garantie. Uw API moet nog steeds haar eigen controles op objectniveau afdwingen (is deze gebruiker eigenaar van dit record?). Een geldig token met een ruime scope is geen vervanging voor autorisatie op de resource zelf.

Rolgebaseerd toegangsbeheer

Opmerking over het abonnement: rolgebaseerd toegangsbeheer is beschikbaar vanaf het abonnement Advanced (en in de proefversie).

Een custom API kan RBAC inschakelen, waardoor het platform de rollen en machtigingen van een gebruiker rechtstreeks opneemt in de tokens die het voor die API uitgeeft. Op het tabblad met instellingen van de API:

  • Rollen en machtigingen opnemen (RBAC) schakelt dit in voor de API.
  • permissions-claim opnemen neemt de verleende scopes van de gebruiker voor deze API op als permissions-claim.
  • roles-claim opnemen neemt de rolnamen van de gebruiker op als roles-claim.

Deze claims worden alleen toegevoegd aan tokens met een gebruiker. De applicatie neemt vervolgens autorisatiebeslissingen op basis van die claims. Zie Rollen om rollen te definiëren en toe te wijzen aan gebruikers en groepen.

Het access token is de plek waar die beslissingen thuishoren. Een roles-claim komt ook in het ID-token terecht wanneer een applicatie de scope roles aanvraagt, maar die is alleen bedoeld voor weergave; zie Afdwingen op het access token, niet op het ID-token.

De API als verifieerbaar contract

Een geregistreerde API is in feite een contract tussen u en de resource server:

  • De identifier is stabiel en wordt de audience van elk token dat ervoor wordt uitgegeven.
  • Het platform ondertekent elk token met zijn ondertekeningssleutel (zie Ondertekeningssleutels).
  • De resource server valideert het token voordat deze een scope vertrouwt: hij controleert de handtekening, of de issuer dit platform is en of de audience overeenkomt met zijn eigen identifier, en leest pas daarna de scopes.

Als een van deze controles mislukt, moet de resource server het verzoek direct weigeren.

De management-API aanroepen (machine-to-machine-quickstart)

Om een script of backendservice de eigen management-API van het platform te laten aanroepen:

  1. Maak een machine-to-machine-applicatie aan; zie Applicaties.
  2. Verleen die applicatie op het tabblad Applicatietoegang van de System API de managementscopes die zij nodig heeft (bijvoorbeeld users.read, groups.write). Verleen alleen de scopes die de integratie daadwerkelijk gebruikt.
  3. Vraag vanuit uw service een token aan met de client-credentials-grant bij het token-endpoint, met de identifier van de System API als audience.
  4. Roep de management-endpoints onder /api/v1/... aan met het geretourneerde token in de header Authorization: Bearer.

Het tabblad Test van de System API genereert precies deze twee opdrachten voor u, vooraf ingevuld met een echte applicatie; kopieer ze als vertrekpunt.

Een token werkt al vóór het verlopen niet meer zodra de applicatie haar toegang op de System API verliest, haar client secret wordt geroteerd of de applicatie wordt verwijderd. De service krijgt dan HTTP 401 en moet een nieuw token aanvragen.

Machine-to-machine-tokenlimieten

Voor tokens die via de client-credentials-grant worden uitgegeven, gelden twee limieten. Beide worden getoond in het overzicht Integraties → API's. Tokens voor interactieve aanmeldingen van gebruikers worden door geen van beide beïnvloed.

Tokenaanvragen per minuut, per client: de doorvoerlimiet. Aanvragen daarboven worden beantwoord met HTTP 429 en een Retry-After-header; de client kan het opnieuw proberen zodra de vertraging uit de header is verstreken.

AbonnementTokenaanvragen per minuut
Trial30
Free60
Essential1.200
Advanced6.000
Pro30.000

Tokens per maand, voor de hele tenant: een volumebudget dat alleen in de instapabonnementen bestaat. Het geldt voor alle machine-to-machine-applicaties en alle API's samen en wordt op de 1e van elke maand teruggezet. Zodra het is verbruikt, worden verdere client-credentials-aanvragen beantwoord met access_denied totdat de volgende maand begint.

AbonnementTokens per maand
Trial / Free1.000
Essential en hogerOnbeperkt

Een client die zijn access token gedurende de volledige levensduur in de cache bewaart, heeft ongeveer 720 tokens per maand nodig en blijft ruim onder beide limieten; een limiet wordt dus normaal gesproken alleen bereikt door een client die voor elke afzonderlijke API-aanroep een nieuw token aanvraagt. Bewaar het token in de cache van de aanroepende service en hergebruik het tot kort voordat het verloopt; de levensduur van het token stelt u per API in op het tabblad met instellingen van de API.

Referentie voor ontwikkelaars / API

Het platform bevat interactieve API-documentatie in het product op /admin/api-docs. Deze toont elk management-endpoint met de parameters en laat u aanroepen in de browser uitproberen, en u kunt de machineleesbare OpenAPI-definitie op dezelfde pagina downloaden.

De management-API omvat het beheer van gebruikers, groepen, organisaties, applicaties, rollen, logs en apparaten. Gebruik /admin/api-docs als gezaghebbende referentie voor endpoints in plaats van een statische lijst hier.

Naslag

TermBetekenis
Identifier (audience)De waarde die de API identificeert; verschijnt in tokens die ervoor worden uitgegeven.
Scope / machtigingEén bevoegdheid die een token kan bevatten.
GebruikersbeleidOf interactieve applicaties namens een gebruiker tokens mogen verkrijgen.
ClientbeleidOf applicaties voor zichzelf tokens mogen verkrijgen (machine-to-machine).
AutorisatieEen uitdrukkelijke toestemming voor één applicatie om deze API met specifieke scopes aan te roepen.
RBACHet opnemen van de rollen en machtigingen van een gebruiker in de tokens van de API.
Token exchangeHet omwisselen van een access token van een gebruiker voor een smaller token voor een andere API (RFC 8693).

Probleemoplossing

  • De tokenaanvraag wordt geweigerd met een ongeldige scope. Een applicatie kan alleen scopes aanvragen die haar op de API zijn verleend. Voeg de scope toe aan de autorisatie van de applicatie voor deze API en vraag daarna een nieuw token aan.
  • Aanroepen retourneren een fout wegens onvoldoende scope, hoewel er een token is uitgegeven. Een verzoek slaagt alleen als het token daadwerkelijk de scope bevat die het endpoint vereist. Decodeer het token en controleer of de verleende scopes deze bevatten; scopes die de applicatie niet zijn verleend, worden zonder melding uit het token weggelaten.
  • Het token heeft de verkeerde audience. Het token moet worden aangevraagd voor de identifier (audience) van deze API. Een token dat voor een andere API of zonder audience is aangemaakt, wordt hier niet geaccepteerd.
  • De tokentest retourneert niets of een fout. De test geeft een token uit voor de geselecteerde applicatie en scopes. Zorg ervoor dat de applicatie een actieve autorisatie op deze API heeft en dat ten minste één scope is geselecteerd.
  • Een token exchange wordt geweigerd. Het subject token moet een nog geldig access token met een gebruiker zijn dat is uitgegeven aan dezelfde applicatie die de uitwisseling uitvoert, de applicatie moet de token-exchange-grant hebben ingeschakeld en de aanvraag moet via resource precies één doel-API noemen. Machine-to-machine-tokens (zonder gebruiker) kunnen niet worden uitgewisseld.

Zie ook de woordenlijst.

Op deze pagina