OAuth 2.1 untuk SpeakNotes API

Penemuan

Kedua dokumen metadata bersifat publik. Klien MCP menemukannya secara otomatis dari tantangan 401 yang dikembalikan 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

Alurnya

1. 1

   Daftarkan klien

   POST ke endpoint pendaftaran dengan URI pengalihan Anda. Klien publik menggunakan PKCE dan tidak mendapatkan rahasia; klien rahasia mendapatkannya. https, loopback http, dan skema aplikasi kustom semuanya diterima.

   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

   Kirim pengguna untuk otorisasi

   Buka endpoint otorisasi dengan id klien, URI pengalihan, cakupan, status, dan tantangan kode S256 Anda. Pengguna masuk, melihat dengan tepat cakupan apa yang Anda minta, dan menyetujui atau menolak.

   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

   Tukarkan kodenya

   POST kode dan verifikator kode Anda ke endpoint token. Kode hanya untuk sekali pakai dan kedaluwarsa dalam satu menit; memutar ulang kode akan mencabut token yang dihasilkannya.

   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

   Segarkan

   Token akses bertahan selama satu jam. Token refresh berotasi setiap kali digunakan, dan menyajikan token yang sudah dicabut akan membatalkan seluruh hibah, yang mencegah token yang dicuri menjadi berguna.

   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

Meminta cakupan

Mintalah seminimal mungkin yang Anda butuhkan. Penyegaran dapat mempersempit cakupan tetapi tidak pernah memperluasnya, dan pengguna dapat melihat serta mencabut aplikasi apa pun dari pengaturan mereka.

Pencabutan

POST token apa pun ke endpoint pencabutan. Mencabut salah satu akan membatalkan pasangan token tersebut. Mencabut token yang tidak pernah ada tetap dianggap berhasil, sesuai RFC 7009.

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