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、ループバック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します。コードは使い捨てで、1分で期限切れになります。一度使用されたコードを再利用すると、そのコードで生成されたトークンが取り消されます。

   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

   リフレッシュ

   アクセストークンの有効期限は1時間です。リフレッシュトークンは使用されるたびに更新されます。取り消されたトークンを提示すると、その許可全体が無効化されます。これにより、盗まれたトークンの悪用を防ぎます。

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