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

   註冊客戶端

   使用您的重新導向 URI 向註冊端點發送 POST 請求。公開客戶端使用 PKCE 且不會獲得密鑰；機密客戶端則會獲得密鑰。支援 https、loopback 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

   交換授權碼

   將授權碼和您的驗證碼發送到權杖端點。授權碼為單次使用，並在一分鐘內過期；重複使用授權碼將會撤銷其產生的權杖。

   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_..."}'