Autentisering

API-et bruker OAuth 2.0 med PKCE for autentisering.

Advarsel
Basic-autentisering fases ut og blir fjernet i en fremtidig oppdatering. Gå over til OAuth 2.0.

Slik fungerer det

Du oppretter en OAuth-applikasjon én gang for å få en client_id
Du omdirigerer brukeren til autorisasjonsendepunktet, der brukeren logger inn
Du får en autorisasjonskode, som du bytter mot et tilgangstoken og et oppdateringstoken
Du bruker tilgangstokenet til å sende API-forespørsler

De fleste klientbiblioteker for OAuth 2.0 håndterer denne flyten automatisk når du peker dem til metadataendepunktet til serveren, /.well-known/oauth-authorization-server.

Alle endepunkter nedenfor er relative til https://api.attendium.com.

Opprett OAuth-applikasjonen din

Opprett en OAuth-applikasjon i Attendium for å få client_id og, hvis det er en konfidensiell applikasjon, client_secret. Du trenger bare å gjøre dette én gang per applikasjon. Se OAuth-applikasjoner.

Omdirigerings-URI-er må bruke https, eller http med en loopback-adresse (localhost, 127.0.0.1 eller ::1) for lokal utvikling. En offentlig applikasjon kan også bruke et privat URI-skjema med omvendt domenenotasjon, for eksempel com.example.app:/oauth/callback.

Når du oppretter en OAuth-applikasjon – enten i Attendium eller gjennom dynamisk klientregistrering – godtar du utviklervilkårene i den versjonen som var publisert på det tidspunktet.

Autoriser

Generer en PKCE-kodeverifikator og en kodeutfordring:

Lag en tilfeldig streng (43–128 tegn av A-Z, a-z, 0-9, -, ., _, ~) – dette er din code_verifier
Beregn SHA-256-hashen av verifikatoren og base64url-kod den – dette er din code_challenge

Omdiriger deretter brukeren til:

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

Brukeren logger inn på Attendium og blir omdirigert tilbake til din redirect_uri med en autorisasjonskode (code) og din state-verdi.

Bytt koden mot tokener

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

En konfidensiell applikasjon må også autentisere seg, enten med Basic-autentisering (client_secret_basic) eller ved å sende client_secret i forespørselens brødtekst (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

Svaret inneholder et access_token og et refresh_token.

Send API-forespørsler

Ta med tilgangstokenet i headeren Authorization:

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

Forny tilgangstokenet

Tokensvaret inneholder feltet expires_in, som angir hvor lenge tilgangstokenet er gyldig. Bruk oppdateringstokenet til å hente et nytt tilgangstoken før det nåværende utløper:

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

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

En konfidensiell applikasjon autentiserer denne forespørselen på samme måte som når autorisasjonskoden byttes.

Dynamisk klientregistrering

Applikasjoner som konfigurerer seg selv ut fra servermetadataene – blant annet KI-assistenter som kobler til via MCP (se Sett opp MCP) – registrerer seg ved å sende en POST-forespørsel til /oauth2/register. Det trenger du ikke hvis du oppretter OAuth-applikasjonen din i Attendium.

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

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

En applikasjon som er registrert på denne måten, vises ikke under «OAuth-applikasjoner», så navnet, omdirigerings-URI-ene og klienthemmeligheten kan ikke endres der.

Videre lesning

OAuth-applikasjoner