OAuth 2.1 para a API do SpeakNotes

Descoberta

Ambos os documentos de metadados são públicos. Clientes MCP os encontram automaticamente a partir do desafio 401 que a API retorna.

# 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

O fluxo

1. 1

   Registrar um cliente

   Faça um POST para o endpoint de registro com seus URIs de redirecionamento. Clientes públicos usam PKCE e não recebem segredo; clientes confidenciais recebem um. HTTPS, loopback HTTP e esquemas de aplicativos personalizados são aceitos.

   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 o usuário para autorizar

   Abra o endpoint de autorização com seu ID de cliente, URI de redirecionamento, escopos, estado e um desafio de código S256. O usuário faz login, vê exatamente quais escopos você solicitou e aprova ou recusa.

   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

   Trocar o código

   Faça um POST do código e do seu verificador de código para o endpoint de token. Os códigos são de uso único e expiram em um minuto; repetir um código revoga os tokens que ele produziu.

   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

   Atualizar

   Os tokens de acesso duram uma hora. Os tokens de atualização rotacionam a cada uso, e apresentar um token revogado encerra toda a concessão, o que impede que um token roubado seja ú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

Solicitando escopos

Peça apenas o mínimo necessário. Uma atualização pode restringir o escopo, mas nunca ampliá-lo, e os usuários podem ver e revogar qualquer aplicativo em suas configurações.

Revogação

Faça um POST de qualquer um dos tokens para o endpoint de revogação. Revogar uma das partes invalida o par. Revogar um token que nunca existiu ainda é considerado um sucesso, conforme a RFC 7009.

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