OAuth 2.1 para la API de SpeakNotes

Descubrimiento

Ambos documentos de metadatos son públicos. Los clientes MCP los encuentran automáticamente a partir del desafío 401 que devuelve la 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

El flujo

1. 1

   Registrar un cliente

   Haz un POST al endpoint de registro con tus URI de redirección. Los clientes públicos usan PKCE y no obtienen secreto; los clientes confidenciales obtienen uno. Se aceptan https, http de loopback y esquemas de aplicaciones personalizadas.

   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

   Enviar al usuario a autorizar

   Abre el endpoint de autorización con tu ID de cliente, URI de redirección, alcances, estado y un desafío de código S256. El usuario inicia sesión, ve exactamente qué alcances solicitaste y aprueba o rechaza.

   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

   Intercambiar el código

   Haz un POST del código y tu verificador de código al endpoint de token. Los códigos son de un solo uso y caducan en un minuto; repetir uno revoca los tokens que produjo.

   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

   Actualizar

   Los tokens de acceso duran una hora. Los tokens de actualización rotan en cada uso, y presentar uno revocado elimina toda la concesión, lo que evita que un token robado sea útil.

   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

Solicitar alcances

Pide lo mínimo que necesites. Una actualización puede reducir el alcance pero nunca ampliarlo, y los usuarios pueden ver y revocar cualquier aplicación desde su configuración.

Revocación

Haz un POST de cualquier token al endpoint de revocación. Revocar una mitad elimina el par. Revocar un token que nunca existió sigue siendo un éxito, según el RFC 7009.

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