OAuth 2.1 für die SpeakNotes API

Discovery

Beide Metadaten-Dokumente sind öffentlich. MCP-Clients finden sie automatisch anhand der 401-Challenge, die die API zurückgibt.

# 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

Der Ablauf

1. 1

   Einen Client registrieren

   Senden Sie einen POST-Request an den Registrierungs-Endpunkt mit Ihren Redirect-URIs. Öffentliche Clients verwenden PKCE und erhalten kein Secret; vertrauliche Clients erhalten eines. https, loopback http und benutzerdefinierte App-Schemata werden alle akzeptiert.

   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

   Den Nutzer zur Autorisierung weiterleiten

   Öffnen Sie den Autorisierungs-Endpunkt mit Ihrer Client-ID, Redirect-URI, Scopes, State und einer S256-Code-Challenge. Der Nutzer meldet sich an, sieht genau, welche Scopes Sie angefordert haben, und genehmigt oder lehnt diese ab.

   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

   Den Code austauschen

   Senden Sie den Code und Ihren Code-Verifier per POST an den Token-Endpunkt. Codes sind nur einmal verwendbar und laufen nach einer Minute ab; die erneute Verwendung eines Codes führt zum Widerruf der daraus erstellten Token.

   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

   Aktualisierung (Refresh)

   Zugriffstoken sind eine Stunde lang gültig. Refresh-Token rotieren bei jeder Verwendung. Die Verwendung eines widerrufenen Tokens führt zum Entzug der gesamten Berechtigung, was verhindert, dass ein gestohlenes Token nützlich ist.

   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 anfordern

Fragen Sie nur das Nötigste an. Eine Aktualisierung kann den Scope einschränken, aber niemals erweitern. Nutzer können jede App in ihren Einstellungen einsehen und widerrufen.

Widerruf

Senden Sie eines der Token per POST an den Widerrufs-Endpunkt. Der Widerruf eines der beiden Token macht das Paar ungültig. Der Widerruf eines Tokens, das nie existierte, gilt gemäß RFC 7009 dennoch als Erfolg.

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