---
title: "الاتصال باستخدام OAuth"
description: "فوّض عملاء MCP وواجهة سطر الأوامر لـ ThunderPhone دون مشاركة مفتاح API."
---

يتيح OAuth لتطبيق ما الاتصال بمؤسسة ThunderPhone واحدة باستخدام الأذونات التي توافق عليها. يجب أن تستخدم عملاء الدليل OAuth افتراضيًا. تظل مفاتيح API الخاصة بالمؤسسة متاحة للعملاء الذين يتطلبون رمز Bearer مهيأً يدويًا.

## الموافقة على اتصال

ابدأ الاتصال في عميل MCP لديك. سجّل الدخول إلى ThunderPhone، وتحقق من اسم التطبيق والأذونات المطلوبة، واختر مؤسسة، ثم حدّد **موافقة**. حدّد **رفض** إذا لم تكن قد بدأت الاتصال أو إذا كنت لا تثق بالتطبيق. يوفّر المطورون أسماء التطبيقات، وهي ليست شارة تحقق.

تكشف أذونات القراءة البيانات المُسمّاة، بما في ذلك التسجيلات والنصوص المفرغة عند طلب `calls:read`. يمكن لأذونات الكتابة تغيير الموارد أو حذفها؛ وقد تؤدي المكالمات والحملات وشراء أرقام الهاتف وعمليات النشر إلى تكاليف أو تؤثر في بيئة الإنتاج. يظل دورك في المؤسسة ساريًا.

لاتصال CLI، افتح رابط التحقق الظاهر في الطرفية، وقارن الرمز المكوّن من ثمانية أحرف، واختر مؤسستك، ثم وافق. لا يمنح مجرد فتح الرابط إمكانية الوصول. تنتهي صلاحية الرموز بعد 15 دقيقة.

## فصل اتصال تطبيق

افتح **المؤسسة → مفاتيح API → التطبيقات المصرح بها** في لوحة التحكم واختر **إلغاء التفويض**. يؤدي ذلك إلى إلغاء التفويض الذي حددته للمؤسسة الحالية، بما في ذلك رموز الوصول والتحديث الخاصة به. أعد الاتصال من التطبيق إذا أردت تفويضه مرة أخرى.

## الاكتشاف لعملاء MCP

استخدم عنوان URL للخادم `https://api.thunderphone.com/v1/mcp`. يتلقى الطلب دون مصادقة صالحة الرمز `401` مع:

```http
WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource"
```

اجلب هذا المستند، ثم اجلب بيانات تعريف خادم التفويض من `https://api.thunderphone.com/.well-known/oauth-authorization-server`. تتوفر بيانات تعريف المورد أيضاً في `/.well-known/oauth-protected-resource/v1/mcp`. استخدم نقاط النهاية المُعادة بدلاً من إنشائها. معرّف المورد هو `https://api.thunderphone.com/v1/mcp`.

يدعم الخادم تدفق رمز التفويض مع **S256 PKCE**، ورموز التحديث الدوّارة، وتسجيل العملاء العام الديناميكي، والإلغاء، ومنح تفويض الجهاز. لا توجد أسرار عملاء أو منح ضمنية. يتوفر اكتشاف OpenID أيضاً في `/.well-known/openid-configuration`؛ ويتضمن حقول خادم التفويض نفسها بالإضافة إلى `subject_types_supported: ["public"]` ونقطة نهاية معلومات المستخدم. لا يتم دعم رموز المعرّف ومستندات بيانات تعريف معرّف العميل (CIMD).

### تسجيل عميل عام

أرسل JSON إلى `POST /v1/oauth/register`:

```json
{
  "client_name": "My MCP client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}
```

احفظ `client_id` المُعاد. يجب أن تستخدم عمليات إعادة التوجيه HTTPS، أو HTTP على `127.0.0.1` أو `localhost`. سجّل عنوان URI الدقيق لرد الاتصال، بما في ذلك منفذه ومساره. تُرفض الأجزاء وبيانات الاعتماد المضمّنة. يجب أن يستخدم `client_uri` و`logo_uri` الاختياريان HTTPS؛ ولا يجلبهما ThunderPhone أثناء التسجيل. يخضع التسجيل لتحديد المعدل. لا تنتهي صلاحية العملاء المسجلين، ويظلون مسجلين عند إلغاء اتصال. تتضمن عمليات رد الاتصال عبر HTTPS كلاً من `https://chatgpt.com/connector/oauth/<id>` و`https://chatgpt.com/connector_platform_oauth_redirect`. يمكن لكل اتصال تسجيل عميله الخاص.

### رمز التفويض

افتح نقطة نهاية التفويض المكتشفة باستخدام `client_id`، و`redirect_uri` المسجل بدقة، و`response_type=code`، و`state` عشوائي، و`scope`، و`code_challenge`، و`code_challenge_method=S256`، و`resource=https://api.thunderphone.com/v1/mcp`. احسب التحدي على أنه ملخص SHA-256 بترميز base64url دون حشو لمتحقق PKCE جديد وعالي الإنتروبيا. تحقق من `state` و`iss` المُعادين قبل استبدال الرمز. تحدد كل استجابة تفويض، بما فيها الرفض وأخطاء البروتوكول، جهة الإصدار باستخدام `iss`، المطابق تماماً لـ `issuer` المكتشف. تُعاد أخطاء العميل أو رد الاتصال غير الصالحين محلياً دون إعادة التوجيه إلى رد الاتصال ذلك.

استبدل الرمز عند `POST /v1/oauth/token` باستخدام ترميز النماذج، مع قبول JSON أيضاً:

```text
grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE verifier>
resource=https://api.thunderphone.com/v1/mcp
```

يُقبل المعلَمة `resource` الاختيارية في طلبيات التفويض والرمز كليهما، بما في ذلك عمليات التحديث وتبادل رموز الأجهزة. عند حذفها، تكون افتراضياً مورد MCP المكتشف. عند وجودها، يجب أن تطابق ذلك المورد تماماً؛ وتُرجع القيم الأخرى `invalid_target`. تحمل رموز الوصول ذلك الجمهور، ويرفض MCP الرموز التي تفتقد إلى جمهور أو تحمل جمهوراً مختلفاً باستخدام `401` وتحدي اكتشاف.

تنتهي صلاحية طلبات التفويض والرموز بعد 10 دقائق. تحتوي كل استجابة رمز على `access_token`، و`token_type` (`Bearer`)، و`expires_in` (3600 ثانية افتراضياً)، و`refresh_token`، و`scope`، و`organization_id`، و`organization_name`. أرسل رموز الوصول عبر رأس `Authorization: Bearer` فقط. لا تضع الرموز مطلقاً في عناوين URL أو السجلات أو التحكم بالمصادر أو المحادثات.

### التحديث والإلغاء

حدّث باستخدام `grant_type=refresh_token` و`client_id` و`refresh_token` و`resource` عند نقطة نهاية الرمز. احفظ رمز التحديث الجديد بصورة ذرية وتوقف عن استخدام القديم. تنتهي صلاحية رموز التحديث بعد 30 يوماً دون تحديث ناجح. يمكن أن يضيّق `scope` اختياري الأذونات الممنوحة. يتم تضمين `offline_access` دائماً، وتُصدر رموز التحديث دائماً. يمنح الطلب الأولي دون `scope` صلاحية `offline_access` فقط، لذا ينبغي للعملاء طلب الأذونات التي يحتاجونها.

يؤدي إعادة استخدام الرمز وإعادة استخدام رمز تحديث دوّار إلى إلغاء التفويض بالكامل. نفّذ عمليات التحديث بشكل متسلسل ضمن العميل؛ إذ إن إعادة تشغيل بيانات اعتماد تم استبدالها بنجاح ليست استراتيجية إعادة محاولة آمنة.

لقطع الاتصال، أرسل `token` و`client_id` إلى `POST /v1/oauth/revoke`. يؤدي إلغاء أي من الرمزين إلى إلغاء تفويضه، بما في ذلك جميع الرموز الصادرة منه. يعيد الرمز غير المعروف نجاحاً دون الإفصاح عما إذا كان موجوداً. يمكن لجلسات لوحة التحكم إدراج تفويضاتها الخاصة عند `GET /v1/oauth/grants` وإلغاء أحدها عند `DELETE /v1/oauth/grants/<id>`، مع استخدام `X-ThunderPhone-Org` لاختيار المؤسسة.

### تفويض الجهاز

يقتصر تفويض الجهاز على العملاء المسجلين مسبقاً؛ ويتلقى العملاء المسجلون ديناميكياً `unauthorized_client`. يدعم العميل العام المسجل مسبقاً `thunderphone-cli` تفويض الجهاز والتحديث. أرسل `client_id=thunderphone-cli` و`scope` إلى `POST /v1/oauth/device/code`. اعرض `user_code` و`verification_uri` للمستخدم، أو افتح `verification_uri_complete`.

استطلع نقطة نهاية الرمز باستخدام `grant_type=urn:ietf:params:oauth:grant-type:device_code` و`client_id` و`device_code`، مع الانتظار لمدة لا تقل عن `interval` المُعاد، وهي 5 ثوانٍ. تابع عند `authorization_pending`. عند `slow_down`، استخدم `interval` الجديد المُعاد في الاستجابة، والذي يزيد بمقدار 5 ثوانٍ، لكل طلب لاحق. توقف عند `access_denied` أو `expired_token` أو أي خطأ آخر. لا توافق على رمز جهاز تلقائياً مطلقاً.

يقبل العميل المسجل مسبقاً `thunderphone-mcp` كلاً من `http://127.0.0.1/callback` و`http://localhost/callback` على أي منفذ. يجب أن يتطابق المخطط والمضيف والمسار والاستعلام؛ ويجب أن يستخدم استبدال الرمز عنوان URI الدقيق لإعادة التوجيه، بما في ذلك المنفذ، من التفويض. يتطلب العملاء المسجلون ديناميكياً مطابقة دقيقة لعنوان URI لإعادة التوجيه، بما في ذلك المنفذ. سجّل رد اتصال مختلفاً ديناميكياً إذا احتجت إلى مسار آخر.

### التحقق من هوية الحساب ونطاق مساحة العمل

اطلب كلاً من `openid email` إلى جانب نطاقات العملية التي يحتاجها عميلك. استدعِ `userinfo_endpoint` المكتشفة (`GET /v1/oauth/userinfo`) باستخدام رمز الوصول في رأس Bearer. تحتوي الاستجابة الناجحة على:

```json
{
  "sub": "123",
  "email": "person@example.com",
  "email_verified": true,
  "name": "Example User",
  "org_id": 456
}
```

`sub` هو معرّف المستخدم الثابت؛ و`org_id` هي المؤسسة المحددة أثناء الموافقة. تتطلب نقطة النهاية نطاقي الهوية كليهما وتعيد `403` إذا كان أحدهما مفقوداً. تعيد `403` مع `error=access_denied` إذا لم يكن للحساب ملف بريد إلكتروني موثّق، بدلاً من تأكيد أن بريداً إلكترونياً غير موثّق موثوق به. تعيد الرموز غير الصالحة أو منتهية الصلاحية أو الملغاة أو ذات الجمهور الخاطئ `401`. لا تستطيع رموز جلسات المستخدم ومفاتيح واجهة برمجة التطبيقات الخاصة بالمؤسسة استدعاء معلومات المستخدم. لا يتم إصدار رمز معرّف.

## الأذونات المتاحة

| الفئة | النطاقات |
| --- | --- |
| الوكلاء واستيراد الوكلاء | `agents:read`, `agents:write` |
| المكالمات | `calls:read`, `calls:write` |
| أرقام الهواتف والمتصلون المحظورون وVoIP | `numbers:read`, `numbers:write` |
| المعرفة | `knowledge:read`, `knowledge:write` |
| الحملات | `campaigns:read`, `campaigns:write` |
| عمليات التكامل ونقاط نهاية webhook وخوادم MCP | `integrations:read`, `integrations:write` |
| الأصوات | `voices:read` |
| سيناريوهات الاختبار وعمليات الاختبار والتحقق | `testing:read`, `testing:write` |
| الفوترة | `billing:read` |
| هوية الحساب والبريد الإلكتروني الموثق | `openid`, `email` (كلاهما مطلوبان لـ userinfo) |
| الاتصال المستمر | `offline_access` (مضمّن دائمًا) |

تستخدم طلبات GET وHEAD وOPTIONS نطاقات القراءة؛ وتستخدم الطرق الأخرى نطاقات الكتابة. لا تتوفر تعديلات الأصوات والفوترة عبر OAuth؛ يستخدم `POST /v1/voices/preview` النطاق `voices:read` لأنه يعاين صوتًا دون تغيير إعداداته. تفرض أدوات MCP نطاق عملية REST الأساسية الخاصة بها. تُرفض عمليات النقل بين المؤسسات حتى عندما ينتمي المستخدم الذي يمنح التفويض إلى كلتا المؤسستين. لا تتوفر عبر OAuth عائلات API الأخرى، بما في ذلك إدارة مفاتيح API وإعدادات الحساب البشري. يؤدي غياب إذن لعملية REST إلى إرجاع `403` مع `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. تُرجع رموز الوصول غير الصالحة أو منتهية الصلاحية `401`.


### إشارات مصادقة أدوات MCP

تتضمن كل أداة في `tools/list` القيمة `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`، مع نطاق عملية REST الخاصة بتلك الأداة. تستخدم أدوات الوثائق العامة قائمة نطاقات فارغة، ولا تزال تتطلب اتصالًا موثّقًا.

يتلقى الرمز المميز الصالح الذي يفتقد نطاق أداة ما HTTP `200` مع `result` بصيغة JSON-RPC يحتوي على `isError: true`، ونص توضيحي في `content`، و`_meta["mcp/www_authenticate"]`. الأخيرة مصفوفة تحتوي على تحدي Bearer مع `resource_metadata` و`error="insufficient_scope"` و`error_description` والنطاق `scope` المطلوب. لا تُنفذ الأداة. استخدم هذا التحدي لطلب موافقة موسعة. تستمر المصادقة المفقودة أو غير الصالحة في إرجاع HTTP `401` مع `WWW-Authenticate`؛ وتستمر حالات فشل نطاق REST في إرجاع HTTP `403`.

## الاحتفاظ ببيانات الاعتماد

تشغّل API الأمر `python manage.py oauth_cleanup` كل ساعة في بيئتي الاختبار المرحلي والإنتاج. يزيل طلبات التفويض ورموز الأجهزة منتهية الصلاحية. لا تُحذف رموز الوصول ورموز التفويض وتجزئات رموز التحديث منتهية الصلاحية إلا بعد إلغاء منحها أو انتهاء صلاحية العائلة بالكامل. تُحتفظ بالتجزئات المستخدمة ما دامت العائلة تحتوي على رمز تحديث أو رمز تفويض أو رمز جهاز معتمد أو رمز وصول قابل للاستخدام، بحيث لا يمكن لعملية التنظيف تعطيل اكتشاف إعادة التشغيل.