OAuth 2.1 cho SpeakNotes API

Khám phá

Cả hai tài liệu siêu dữ liệu đều công khai. Các ứng dụng khách MCP sẽ tự động tìm thấy chúng từ thử thách 401 mà API trả về.

# 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

Quy trình

1. 1

   Đăng ký ứng dụng khách

   Gửi yêu cầu POST đến điểm cuối đăng ký với các URI chuyển hướng của bạn. Các ứng dụng khách công khai sử dụng PKCE và không nhận được bí mật; các ứng dụng khách bảo mật sẽ nhận được một bí mật. Các giao thức https, loopback http và các lược đồ ứng dụng tùy chỉnh đều được chấp nhận.

   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

   Gửi người dùng đi ủy quyền

   Mở điểm cuối ủy quyền với id ứng dụng khách, URI chuyển hướng, phạm vi, trạng thái và thử thách mã S256 của bạn. Người dùng đăng nhập, xem chính xác các phạm vi bạn đã yêu cầu và phê duyệt hoặc từ chối.

   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

   Trao đổi mã

   Gửi mã và trình xác minh mã của bạn đến điểm cuối mã thông báo qua POST. Các mã chỉ được sử dụng một lần và hết hạn trong một phút; việc phát lại mã sẽ thu hồi các mã thông báo mà nó đã tạo ra.

   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

   Làm mới

   Mã truy cập có thời hạn một giờ. Mã làm mới sẽ xoay vòng sau mỗi lần sử dụng, và việc trình bày một mã đã bị thu hồi sẽ hủy bỏ toàn bộ quyền truy cập, giúp ngăn chặn việc sử dụng mã bị đánh cắp.

   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

Yêu cầu phạm vi

Chỉ yêu cầu những gì bạn thực sự cần. Việc làm mới có thể thu hẹp phạm vi nhưng không bao giờ mở rộng nó, và người dùng có thể xem và thu hồi bất kỳ ứng dụng nào từ cài đặt của họ.

Thu hồi

Gửi bất kỳ mã thông báo nào đến điểm cuối thu hồi qua POST. Việc thu hồi một nửa sẽ hủy bỏ cả cặp. Việc thu hồi một mã thông báo chưa từng tồn tại vẫn được coi là thành công, theo RFC 7009.

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