OAuth 2.1 لواجهة برمجة تطبيقات SpeakNotes

الاكتشاف

كلا مستندي البيانات الوصفية متاحان للجمهور. تكتشفها عملاء MCP تلقائياً من تحدي 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

   تسجيل عميل

   أرسل طلب POST إلى نقطة نهاية التسجيل مع عناوين URI لإعادة التوجيه الخاصة بك. يستخدم العملاء العامون 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

   إرسال المستخدم للتفويض

   افتح نقطة نهاية التفويض باستخدام معرف العميل الخاص بك، و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 إلى نقطة نهاية الرمز المميز. الأكواد مخصصة للاستخدام مرة واحدة وتنتهي صلاحيتها خلال دقيقة؛ إعادة استخدام كود تؤدي إلى إبطال الرموز التي أنتجها.

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