وصول محدد الأذونات يبقى تحت سيطرتك

الاتصالات رموز لمساحات العمل

ينشئ مالكو مساحة العمل ومديروها الاتصالات من صفحة المطورون. كل اتصال رمز حامل مرتبط بمساحة عمل واحدة وجهة استخدام واحدة: تعمل رموز rest (sw_rest_...) مع /api/v1 فقط، وتعمل رموز mcp (sw_mcp_...) مع /mcp فقط.

أرسل الرمز في ترويسة Authorization. لا تضعه أبدًا في عنوان URL أو سلسلة استعلام أو ملف استيراد أو حزمة متصفح.

Authorization: Bearer sw_rest_...

تضيّق نطاقات الأذونات ما يسمح به دورك

يبدأ الاتصال الجديد بالخيارات الافتراضية للقراءة فقط: workspaces:read وcatalog:read وworlds:read. أضف ما تحتاجه المهمة فقط، مثل worlds:write لتعديل المسودات أو worlds:publish للنشر. يحتاج GET /me إلى account:read.

لا يمنح نطاق الأذونات أبدًا أكثر مما يستطيع منشئ الرمز فعله، وتُقرأ صلاحية ذلك الدور مجددًا في كل طلب. تجيب معرفات مساحة عمل أخرى بالرمز 404، فلا يستطيع الرمز اكتشاف ما لا يجوز له رؤيته.

الأذونات الحساسة اختيارية

لا تُحدد مسبقًا أبدًا نطاقات الأذونات التي تصل إلى عناوين المشتركين أو رسائل الزوار أو الفوترة أو الحذف أو كتابة DNS أو الإنفاق أو تغييرات الفريق أو خطافات الويب. تتطلب إضافة أحدها تسجيل دخولك مجددًا أولًا. وتبقى أدوات MCP المقابلة مخفية حتى يمتلك الرمز تلك الأذونات.

بعض الإجراءات غير متاحة للرمز مطلقًا: البت في الموافقات وحذف الكازا والحسابات أو استعادتها (تتطلب تسجيل دخول جديدًا مباشرة إلى المنصة وتجيب بـ 403 reauthentication_required) وتصدير البيانات.

انتهاء الصلاحية والتدوير والإلغاء

• تنتهي صلاحية الرموز بعد 30 يومًا افتراضيًا وبعد 90 يومًا كحد أقصى.
• لا تُخزن إلا قيمة تجزئة، لذا لا يمكن عرض رمز مفقود مجددًا. أنشئ اتصالًا جديدًا بدلًا من ذلك.
• للتدوير، أنشئ اتصالًا جديدًا وحوّل عميلك إليه ثم ألغِ القديم. يسري الإلغاء عند الطلب التالي، بما في ذلك العمل الذي وضعه وكيل في قائمة الانتظار.

أخطاء متوقعة

• 401: الرمز مفقود أو مجهول أو منتهي الصلاحية أو ملغى أو مخصص لجهة الاستخدام الأخرى.
• 403 insufficient_scope: يفتقر الرمز إلى إذن. تسميه context.required_scope ويحمل الرد ترويسة WWW-Authenticate.
• 404: المورد غير موجود في مساحة عمل هذا الرمز.

OAuth غير متاح بعد

لا يستطيع عملاء الوكلاء الذين يدعمون تسجيل الدخول عبر OAuth فقط الاتصال بعد. ولهذا لا يسرد /.well-known/oauth-protected-resource/mcp أي خادم تفويض. استخدم رمز اتصال في إعدادات ترويسات العميل بدلًا من ذلك.