OAuth 2.1 voor de SpeakNotes API

Discovery

Beide metadatadocumenten zijn openbaar. MCP-clients vinden ze automatisch via de 401-uitdaging die de API retourneert.

# Authorization server metadata (RFC 8414)
curl https://speaknotes.io/.well-known/oauth-authorization-server

# Protected resource metadata (RFC 9728)
curl https://api.speaknotes.io/.well-known/oauth-protected-resource

De flow

1. 1

   Een client registreren

   POST naar het registratie-eindpunt met uw redirect-URI's. Publieke clients gebruiken PKCE en krijgen geen geheim; vertrouwelijke clients krijgen er wel een. https, loopback http en aangepaste app-schema's worden allemaal geaccepteerd.

   curl -X POST https://api.speaknotes.io/oauth/register \
     -H "Content-Type: application/json" \
     -d '{
       "client_name": "Your app",
       "redirect_uris": ["https://your.app/callback"],
       "token_endpoint_auth_method": "none",
       "scope": "notes:read notes:write summaries:write"
     }'

2. 2

   Stuur de gebruiker door voor autorisatie

   Open het autorisatie-eindpunt met uw client-id, redirect-URI, scopes, state en een S256-code-challenge. De gebruiker logt in, ziet precies welke scopes u heeft gevraagd en keurt deze goed of wijst ze af.

   https://speaknotes.io/oauth/authorize
     ?client_id=sn_client_...
     &redirect_uri=https://your.app/callback
     &response_type=code
     &scope=notes:read%20summaries:write
     &state=RANDOM
     &code_challenge=BASE64URL_SHA256_OF_VERIFIER
     &code_challenge_method=S256

3. 3

   De code inwisselen

   POST de code en uw code-verifier naar het token-eindpunt. Codes zijn voor eenmalig gebruik en verlopen na een minuut; het opnieuw gebruiken van een code trekt de tokens in die ermee zijn geproduceerd.

   curl -X POST https://api.speaknotes.io/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "client_id": "sn_client_...",
       "code": "...",
       "redirect_uri": "https://your.app/callback",
       "code_verifier": "..."
     }'

4. 4

   Verversen

   Toegangstokens zijn een uur geldig. Verversingstokens roteren bij elk gebruik, en het presenteren van een ingetrokken token beëindigt de hele toewijzing, wat voorkomt dat een gestolen token bruikbaar blijft.

   curl -X POST https://api.speaknotes.io/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "refresh_token",
       "client_id": "sn_client_...",
       "refresh_token": "sn_rt_..."
     }'

access_token: 1h · refresh_token: 60d, rotating · code: 60s, single use

Scopes aanvragen

Vraag alleen om wat u echt nodig heeft. Een verversing kan de scope verkleinen, maar nooit vergroten, en gebruikers kunnen elke app in hun instellingen inzien en intrekken.

Intrekking

POST een van beide tokens naar het intrekkingseindpunt. Het intrekken van de ene helft beëindigt het paar. Het intrekken van een token dat nooit heeft bestaan is nog steeds een succes, volgens RFC 7009.

curl -X POST https://api.speaknotes.io/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"client_id": "sn_client_...", "token": "sn_rt_..."}'