Authenticatie

De API gebruikt OAuth 2.0 met PKCE voor authenticatie.

Waarschuwing
Basisauthenticatie is verouderd en wordt in een toekomstige update verwijderd. Stap over op OAuth 2.0.

Zo werkt het

Je maakt eenmalig een OAuth-applicatie aan om een client_id te krijgen
Je stuurt de gebruiker door naar het autorisatie-endpoint, waar de gebruiker inlogt
Je ontvangt een authorization code, die je inwisselt voor een toegangstoken en een refreshtoken
Je gebruikt het toegangstoken om API-verzoeken te doen

De meeste OAuth 2.0-clientbibliotheken handelen deze flow automatisch af als je ze naar het servermetadata-endpoint /.well-known/oauth-authorization-server verwijst.

Alle endpoints hieronder zijn relatief ten opzichte van https://api.attendium.com.

Je OAuth-applicatie aanmaken

Maak in Attendium een OAuth-applicatie aan om je client_id te krijgen, en je client_secret als het een vertrouwelijke applicatie is. Je hoeft dit maar één keer per applicatie te doen. Zie OAuth-applicaties.

Redirect-URI's moeten https gebruiken, of http met een loopbackadres (localhost, 127.0.0.1 of ::1) voor lokale ontwikkeling. Een openbare applicatie kan ook een private-use-URI-schema met omgekeerde domeinnaam gebruiken, zoals com.example.app:/oauth/callback.

Door een OAuth-applicatie aan te maken – in Attendium of via dynamische clientregistratie – ga je akkoord met de ontwikkelaarsvoorwaarden in de versie die op dat moment is gepubliceerd.

Autoriseren

Genereer een PKCE-code-verifier en -code-challenge:

Maak een willekeurige tekenreeks (43–128 tekens, met A-Z, a-z, 0-9, -, ., _, ~) – dit is je code_verifier
Bereken de SHA-256-hash van de verifier en codeer deze met base64url – dit is je code_challenge

Stuur de gebruiker daarna door naar:

GET /oauth2/authorize?response_type=code
  &client_id=your-client-id
  &redirect_uri=https://yourapp.example.com/callback
  &code_challenge=your-code-challenge
  &code_challenge_method=S256
  &state=random-state-value

De gebruiker logt in bij Attendium en wordt teruggestuurd naar je redirect_uri met een authorization code (code) en je state-waarde.

De code inwisselen voor tokens

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

grant_type=authorization_code
&client_id=your-client-id
&redirect_uri=https://yourapp.example.com/callback
&code=the-authorization-code
&code_verifier=your-code-verifier

Een vertrouwelijke applicatie moet zich ook zelf authenticeren, met basisauthenticatie (client_secret_basic) of door client_secret in de body van het verzoek mee te sturen (client_secret_post):

POST /oauth2/token
Authorization: Basic base64(your-client-id:your-client-secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&redirect_uri=https://yourapp.example.com/callback
&code=the-authorization-code
&code_verifier=your-code-verifier

Het antwoord bevat een access_token en een refresh_token.

API-verzoeken doen

Neem het toegangstoken op in de Authorization-header:

curl -H "Authorization: Bearer your-access-token" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ me { id } }"}' \
     https://api.attendium.com/graphql

Het toegangstoken vernieuwen

Het tokenantwoord bevat een veld expires_in dat aangeeft hoe lang het toegangstoken geldig is. Gebruik het refreshtoken om een nieuw toegangstoken op te halen voordat het huidige verloopt:

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

grant_type=refresh_token
&client_id=your-client-id
&refresh_token=your-refresh-token

Een vertrouwelijke applicatie authenticeert dit verzoek op dezelfde manier als bij het inwisselen van de authorization code.

Dynamische clientregistratie

Applicaties die zichzelf configureren op basis van de servermetadata – waaronder AI-assistenten die via MCP verbinding maken (zie MCP instellen) – registreren zichzelf door een POST-verzoek naar /oauth2/register te sturen. Dit heb je niet nodig als je je OAuth-applicatie in Attendium aanmaakt.

POST /oauth2/register
Content-Type: application/json

{
  "redirect_uris": ["https://yourapp.example.com/callback"],
  "client_name": "Mijn applicatie"
}

Een applicatie die op deze manier is geregistreerd, staat niet bij ‘OAuth-applicaties’, dus de naam, de redirect-URI's en het clientgeheim kunnen daar niet worden gewijzigd.

Verder lezen

OAuth-applicaties