OAuth 2.1 pour l'API SpeakNotes

Découverte

Les deux documents de métadonnées sont publics. Les clients MCP les trouvent automatiquement à partir du défi 401 renvoyé par l'API.

# 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

Le flux

1. 1

   Enregistrer un client

   Effectuez une requête POST vers le point de terminaison d'enregistrement avec vos URI de redirection. Les clients publics utilisent PKCE et n'obtiennent aucun secret ; les clients confidentiels en reçoivent un. Les schémas https, http en boucle locale (loopback) et les schémas d'application personnalisés sont tous acceptés.

   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

   Envoyez l'utilisateur pour autorisation

   Ouvrez le point de terminaison d'autorisation avec votre identifiant client, votre URI de redirection, vos portées (scopes), votre état et un défi de code S256. L'utilisateur se connecte, voit exactement quelles portées vous avez demandées, puis approuve ou refuse.

   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

   Échangez le code

   Envoyez le code et votre vérificateur de code par POST au point de terminaison de jeton. Les codes sont à usage unique et expirent en une minute ; la réutilisation d'un code révoque les jetons qu'il a produits.

   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

   Actualisation

   Les jetons d'accès durent une heure. Les jetons d'actualisation tournent à chaque utilisation, et la présentation d'un jeton révoqué annule toute l'autorisation, ce qui empêche l'utilisation d'un jeton volé.

   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

Demande de portées (scopes)

Demandez le strict minimum. Une actualisation peut réduire la portée mais jamais l'élargir, et les utilisateurs peuvent voir et révoquer n'importe quelle application depuis leurs paramètres.

Révocation

Envoyez l'un ou l'autre jeton par POST au point de terminaison de révocation. Révoquer l'une des deux parties annule la paire. Révoquer un jeton qui n'a jamais existé est considéré comme un succès, conformément à la RFC 7009.

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