OAuth 2.1 สำหรับ SpeakNotes API

การค้นพบ (Discovery)

เอกสารข้อมูลเมตาทั้งสองรายการเป็นสาธารณะ ไคลเอ็นต์ MCP จะค้นพบเอกสารเหล่านี้โดยอัตโนมัติจากความท้าทาย 401 ที่ 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

ขั้นตอนการทำงาน

1. 1

   ลงทะเบียนไคลเอ็นต์

   ส่งคำขอ POST ไปยังจุดสิ้นสุดการลงทะเบียนพร้อมกับ redirect URI ของคุณ ไคลเอ็นต์สาธารณะจะใช้ PKCE และไม่ได้รับ secret ส่วนไคลเอ็นต์ที่มีความปลอดภัยจะได้รับ secret รองรับทั้ง https, loopback http และ custom app schemes

   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

   ส่งผู้ใช้ไปตรวจสอบสิทธิ์

   เปิดจุดสิ้นสุดการอนุญาตด้วย client id, redirect URI, ขอบเขต, state และ S256 code challenge ของคุณ ผู้ใช้จะลงชื่อเข้าใช้ เห็นขอบเขตที่คุณร้องขออย่างชัดเจน และเลือกอนุมัติหรือปฏิเสธ

   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

   แลกเปลี่ยนรหัส (Exchange the code)

   ส่งคำขอ POST รหัสและ code verifier ของคุณไปยังจุดสิ้นสุดโทเค็น รหัสสามารถใช้ได้ครั้งเดียวและหมดอายุในหนึ่งนาที การใช้รหัสซ้ำจะทำให้โทเค็นที่สร้างขึ้นถูกเพิกถอน

   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

   การรีเฟรช

   Access token มีอายุหนึ่งชั่วโมง Refresh token จะหมุนเวียนทุกครั้งที่ใช้งาน และการนำโทเค็นที่ถูกเพิกถอนมาใช้จะทำให้การอนุญาตทั้งหมดสิ้นสุดลง ซึ่งเป็นวิธีป้องกันไม่ให้โทเค็นที่ถูกขโมยไปใช้งานได้

   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 ไปยังจุดปลายทาง (endpoint) การเพิกถอนสิทธิ์ โดยการเพิกถอนส่วนใดส่วนหนึ่งจะทำให้ทั้งคู่ใช้งานไม่ได้ การเพิกถอนโทเค็นที่ไม่เคยมีอยู่จริงยังคงถือว่าสำเร็จ ตามมาตรฐาน RFC 7009

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