الإدارة

مفاتيح API وعملاء OAuth

أنشئ مفاتيح API محدودة النطاق للسكربتات وCI، وسجّل عملاء OAuth للتطبيقات التي تتصرف باسم مستخدم، وألغِ أياً منهما حين تنتهي.

لدى Polylane نوعان من بيانات الاعتماد للوصول البرمجي. تلائم مفاتيح API السكربتات وCI والأدوات بلا واجهة: مفتاح واحد، ومساحة عمل واحدة، ومجموعة ثابتة من النطاقات. ويلائم عملاء OAuth التطبيقات التي تسجّل دخول المستخدمين وتستدعي Polylane باسمهم، ويصادق كلاهما على API نفسها.

مفاتيح API

افتح Settings > API Keys في وحدة التحكم وانقر Create an API key. سمّ المفتاح (4 أحرف على الأقل) واختر نطاقاته: يحدد النموذج مسبقاً النطاقات التي تحملها عضويتك، ويفشل طلب نطاق لا تحمله بـ 403. يُعرض المفتاح مرة واحدة، ويبدأ بـ sk_، ولا يمكن عرضه مرة أخرى، فانسخه إلى مدير الأسرار لديك.

أرسل المفتاح في الترويسة x-api-key:

Terminal

curl https://api.polylane.com/v1/scopes \
  -H "x-api-key: sk_xxxxx"

تُفوَّض الطلبات مقابل نطاقات المفتاح، لا أذوناتك الكاملة. ألغِ مفتاحاً من صفحة الإعدادات نفسها أو بـ DELETE إلى /v1/api_keys/{workspaceId}/{id}؛ ويستطيع منشئ المفتاح أو مسؤول مساحة العمل حذفه.

النطاقات

تقرن النطاقات مورداً بإجراء، ويسرد GET /v1/scopes كل واحد منها مع وصفه. هذه النطاقات التي ستقابلها أكثر من غيرها عبر هذه الوثائق.

النطاق	الوصف
`threads:read`	عرض المحادثات.
`issues:write`	الإقرار بالمشكلات أو حلّها أو إعادة تشغيل فحوصها.
`cloud_infra:read`	عرض عقد البنية التحتية السحابية وحوافها.
`autofixes:write`	تسجيل حالة دورة حياة الإصلاح التلقائي وتحديثها.
`agent_tools:read`	اكتشاف أدوات الوكلاء للقراءة فقط وتشغيلها من عملاء خارجيين مثل MCP.
`agent_tools:write`	تشغيل أدوات الوكلاء القادرة على الكتابة من عملاء خارجيين، رهناً بمراجعة الأمان.
`oauth_clients:write`	إنشاء عملاء OAuth وإدارتهم.
`analytics:read`	عرض نشاط مساحة العمل والمحتوى الشائع وإحصاءات الاستخدام.

عملاء OAuth

عميل OAuth تطبيق تسجّله ليستطيع تسجيل دخول المستخدمين واستدعاء Polylane بالنطاقات التي يوافق عليها كل مستخدم؛ وتتطلب إدارة العملاء oauth_clients:write. افتح Settings > OAuth Clients وانقر New OAuth client: يظهر الاسم وبريد التواصل على شاشة الموافقة، وتضيف عناوين URI لإعادة التوجيه والنطاقات التي يجوز للعميل طلبها، والوصف والموقع والشعار اختيارية. يعيد الإنشاء معرّف عميل يبدأ بـ oauth_client_ وسرّ عميل يُعرض مرة واحدة؛ وإذا فقدت السر، فدوّره بـ Rotate من صفحة العميل ويتوقف السر السابق عن العمل فوراً.

تدفق التفويض

ينفّذ Polylane تدفق رمز التفويض في OAuth 2.0 مع PKCE (S256).

أرسل المستخدم إلى صفحة الموافقة

https://console.polylane.com/oauth/<client-id>
  ?client_id=<client-id>
  &redirect_uri=https://example.com/callback
  &scope=threads:read%20issues:read
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &state=<random-state>

يجب أن يطابق URI إعادة التوجيه تماماً واحداً سجّلته، ويجب أن يكون كل نطاق مطلوب واحداً مُنح للعميل.

بادل الرمز بالرموز

بعد موافقة المستخدم، يعيد Polylane التوجيه إلى رد النداء لديك مع code. بادله على خادمك الخلفي:

Terminal

curl -X POST https://api.polylane.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "<code>",
       "redirect_uri": "https://example.com/callback",
       "client_id": "<client-id>", "client_secret": "<client-secret>",
       "code_verifier": "<verifier>"}'

تحمل الاستجابة access_token تنتهي صلاحيته بعد ساعة واحدة وrefresh_token.

استدعِ API باسم المستخدم

Terminal

curl https://api.polylane.com/v1/scopes \
  -H "Authorization: Bearer <access-token>"

حدّث حين تنتهي صلاحية رمز الوصول

أرسل grant_type بقيمة refresh_token إلى نقطة نهاية الرمز نفسها بطلب POST. رموز التحديث للاستخدام مرة واحدة: يعيد كل تحديث بديلاً.

تُنشر بيانات الخادم الوصفية، بما في ذلك كل عنوان URL لنقاط النهاية، على https://api.polylane.com/v1/.well-known/oauth-authorization-server، ويعرض المزود أيضاً /v1/oauth/userinfo و/v1/oauth/introspect. ألغِ رمزاً يحمله تطبيقك بـ POST إلى /v1/oauth/revoke يحمل الرمز وبيانات اعتماد عميلك، مع ضبط token_type_hint على access_token أو refresh_token، أو حذفه لتجربة الاثنين. ويمنع حذف العميل من صفحته بدء تفويضات أخرى.

وكلاء البرمجة

لا تحتاج إلى عميل OAuth لربط وكيل برمجة. يشغّل خادم MCP المستضاف على https://mcp.polylane.com/mcp تدفق OAuth الخاص به بتسجيل عملاء ديناميكي ويقبل مفتاح API أيضاً؛ انظر خادم MCP الخاص بالمنصة.