OAuth 2.1 per l'API di SpeakNotes

Discovery

Entrambi i documenti di metadati sono pubblici. I client MCP li trovano automaticamente dalla sfida 401 restituita dall'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

Il flusso

1. 1

   Registra un client

   Invia una richiesta POST all'endpoint di registrazione con i tuoi URI di reindirizzamento. I client pubblici usano PKCE e non ottengono alcun segreto; i client riservati ne ottengono uno. Sono accettati https, http loopback e schemi di app personalizzati.

   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

   Invia l'utente ad autorizzare

   Apri l'endpoint di autorizzazione con il tuo client id, URI di reindirizzamento, ambiti, stato e una sfida di codice S256. L'utente accede, vede esattamente quali ambiti hai richiesto e approva o rifiuta.

   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

   Scambia il codice

   Invia il codice e il tuo verificatore di codice all'endpoint del token tramite POST. I codici sono monouso e scadono in un minuto; riutilizzarne uno revoca i token che ha prodotto.

   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

   Aggiornamento

   I token di accesso durano un'ora. I token di aggiornamento ruotano a ogni utilizzo e presentare un token revocato annulla l'intera concessione, il che impedisce a un token rubato di essere utile.

   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

Richiesta di ambiti

Chiedi solo il minimo indispensabile. Un aggiornamento può restringere l'ambito ma mai ampliarlo, e gli utenti possono vedere e revocare qualsiasi app dalle loro impostazioni.

Revoca

Invia uno dei due token all'endpoint di revoca tramite POST. Revocare una metà annulla la coppia. Revocare un token mai esistito è comunque un successo, secondo RFC 7009.

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