适用于 SpeakNotes API 的 OAuth 2.1

发现

两个元数据文档都是公开的。MCP 客户端会自动从 API 返回的 401 质询中找到它们。

# 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

流程

1. 1

   注册客户端

   向注册端点发送 POST 请求，并附上您的重定向 URI。公共客户端使用 PKCE 且不获取密钥；机密客户端则会获取一个密钥。支持 https、回环 http 以及自定义应用方案。

   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

   发送用户进行授权

   使用您的客户端 ID、重定向 URI、作用域、状态和 S256 代码质询打开授权端点。用户登录后，将看到您请求的具体作用域，并选择批准或拒绝。

   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

   交换代码

   将代码和您的代码验证器 POST 到令牌端点。代码为一次性使用，一分钟内过期；重用代码将撤销其生成的令牌。

   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

   刷新

   访问令牌有效期为一小时。刷新令牌在每次使用时都会轮换，提交已撤销的令牌将导致整个授权失效，这能防止被盗令牌被滥用。

   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

请求作用域

仅请求您所需的最少权限。刷新操作可能会缩小作用域但绝不会扩大，用户可以在设置中查看并撤销任何应用的权限。

撤销

将任一令牌 POST 到撤销端点。撤销其中一个即会终止整个令牌对。根据 RFC 7009，撤销一个不存在的令牌仍视为成功。

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