مفاتيح API في مُبَرمِج — إنشاء المفتاح وصلاحياته ونسخه وإبطاله

أين تجد الصفحة

من القائمة الجانبية في لوحة التحكم اختر «مفاتيح API»، أو افتح /api-keys مباشرة. الصفحة تتطلّب تسجيل الدخول، وإن انتهت جلستك أثناء فتحها تعيدك إلى صفحة الدخول ثم إليها. تحت العنوان تجد النص: «أنشئ مفاتيح API للوصول لخدمات Moparmeg برمجياً (ومنها تطبيق مبرمج لسطح المكتب). المفتاح يظهر مرة واحدة فقط، وصلاحياته تُختار عند إنشائه ولا تتغيّر بعده.» وتحته رابطان: «كيف تنشئ المفتاح وتستعمله» (هذه الصفحة) و«مرجع الواجهة البرمجية».

إنشاء مفتاح جديد

1. في مربع «إنشاء مفتاح جديد» اكتب اسماً يذكّرك بمكان استعمال المفتاح، في الحقل الذي يقول «اسم المفتاح (مثال: تطبيق سطح المكتب)».
2. تحت «الصلاحيات» أبقِ محدَّداً ما يحتاجه برنامجك فقط (انظر الصلاحيات). المحدَّد مسبقاً كل الصلاحيات عدا النشر وطلب شراء النطاقات.
3. اضغط «إنشاء» (يتحوّل إلى «جارٍ...» أثناء الإنشاء). يبقى الزر معطّلاً ما دام الاسم فارغاً أو لم تُحدَّد أي صلاحية.
4. يظهر المفتاح كاملاً في شريط أعلى القائمة — انسخه فوراً (انظر النسخ).

قواعد الخادم:

• الاسم مطلوب، وأقصاه 64 محرفاً؛ وإلا تظهر رسالة «الاسم يتجاوز 64 محرفاً».
• لكل حساب 20 مفتاحاً فعّالاً على الأكثر. عند بلوغها تظهر «بلغتَ الحدّ الأقصى (20 مفتاحاً) — أبطِل مفتاحاً قبل سكّ آخر». المفاتيح المُبطَلة لا تُحسب.
• الصلاحيات تُحفظ مع المفتاح ولا تُعدَّل بعده: لتغييرها أنشئ مفتاحاً بالصلاحيات الجديدة وأبطل القديم.
• إنشاء المفتاح متاح لكل حساب، لكن استعماله في النداءات يحتاج باقة مدفوعة (انظر التوفّر حسب الباقة).

الصلاحيات

كل صلاحية تظهر في النموذج باسمها وتحته معرّفها. نقطة النهاية لا تُفتح إلا لمفتاح يحمل صلاحيتها؛ وإلا يُرفض النداء بـ403 والرمز API_KEY_SCOPE_REQUIRED، ويحمل الرد اسم الصلاحية الناقصة في الحقل scope.

بجانب الصلاحيتين غير المحدَّدتين مسبقاً تنبيهان: «ينشر مواقعك للعالم — اختره عمداً» لـpublish، و«يطلب شراء نطاقات بمالٍ حقيقي — اختره عمداً» لـdomains:write. أما GET /api/v1/me فيقبل أي مفتاح صالح بلا صلاحية، والقوالب والأقسام والتنزيلات عامة لا تحتاج مفتاحاً — التفاصيل في مرجع الواجهة البرمجية.

المفاتيح القديمة

مفتاح أُنشئ قبل الصلاحيات تظهر على بطاقته «مفتاح قديم بلا صلاحيات: توليد الكود وقائمة المشاريع وإنشاؤها فقط». يبقى يعمل على POST /api/v1/ai وGET وPOST /api/v1/projects (وعلى GET /api/v1/me)، ويُرفض بـ403 على كل نقطة نهاية أخرى. لا يُرقّى تلقائياً: لتصل إلى البقية أنشئ مفتاحاً بصلاحيات وأبطل القديم.

النسخ: المفتاح يظهر مرة واحدة

بعد الإنشاء يظهر الشريط «تم إنشاء المفتاح بنجاح! انسخه الآن — لن يظهر مرة أخرى.» وبجانب المفتاح زر «نسخ» يتحوّل إلى «تم النسخ!» لثانيتين. يبقى الشريط ظاهراً حتى تغادر الصفحة أو تعيد تحميلها أو تنشئ مفتاحاً آخر.

شكل المفتاح: البادئة mop_ يليها 32 محرفاً من A-Z a-z 0-9 _ - (المجموع 36 محرفاً)، مولَّدة من 24 بايتاً عشوائياً. الخادم لا يحفظ المفتاح نفسه، بل بصمته (sha-256) وآخر أربعة محارف منه. لذلك لا يمكن استرجاع مفتاح ضاع، لا منك ولا من الدعم: أنشئ مفتاحاً جديداً وأبطل القديم.

Authorization: Bearer mop_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

قائمة المفاتيح

كل مفتاح فعّال يظهر ببطاقة فيها:

• الاسم الذي اخترته.
• المفتاح مخفياً بهذا الشكل: mop_••••••••abcd — البادئة وثماني نقاط وآخر أربعة محارف، لتميّز مفاتيحك بعضها عن بعض دون كشفها.
• «أُنشئ:» بتاريخ الإنشاء، و«آخر استخدام:» إن استُعمل المفتاح. تاريخ آخر استخدام يُحدَّث مرة كل دقيقة على الأكثر، فهو تقريبي بدقة الدقيقة.
• صلاحيات المفتاح بأسمائها، أو ملاحظة المفتاح القديم إن أُنشئ قبل الصلاحيات.

إن لم يكن لديك مفاتيح تظهر «لا توجد مفاتيح API بعد» و«أنشئ مفتاحك الأول من النموذج أعلاه». المفاتيح المُبطَلة لا تظهر في القائمة.

إبطال مفتاح

1. اضغط «إلغاء المفتاح» على بطاقة المفتاح.
2. يظهر زرّان: «تأكيد الحذف» لإبطاله، أو «إلغاء» للتراجع.

الإبطال فوري: الخادم يفحص حالة المفتاح في كل نداء، فأول نداء بعد الإبطال يُرفض بـ401. الإبطال لا يُمحى معه السجل (يبقى أثر من استعمل ماذا ومتى)، لكن لا توجد طريقة لإعادة تفعيل مفتاح مُبطَل — أنشئ غيره.

تُبطَل كل مفاتيحك تلقائياً مع جلساتك عند تغيير كلمة المرور أو استعادتها، وعند حذف الحساب أو إيقافه. وحساب محذوف لا يفتحه أي مفتاح حتى لو فلت من الإبطال.

انتهاء الصلاحية

الخادم يدعم عمراً اختيارياً للمفتاح بين 1 و365 يوماً عبر الحقل expiresInDays عند الإنشاء؛ وبعد انتهائه يُرفض المفتاح بـ401 كالمُبطَل. المفتاح بلا عمر محدد لا ينتهي حتى تبطله.

تحديد عمر المفتاح من نموذج الصفحة: غير متاح بعد — النموذج يرسل الاسم والصلاحيات فقط، وتاريخ الانتهاء لا يظهر في بطاقة المفتاح. يمكن تحديد العمر بنداء POST /api/v1/api-keys من المتصفح نفسه وأنت مسجّل الدخول؛ التفاصيل في مرجع الواجهة البرمجية.

التوفّر حسب الباقة

سقف نداءات المفتاح في الساعة يساوي حصة الذكاء الاصطناعي اليومية لباقتك، والباقة التي حصتها صفر لا تستعمل الواجهة البرمجية أصلاً. السقف لحسابك لا لكل مفتاح: إنشاء مفتاح ثانٍ لا يضاعفه. نداءات GET /api/v1/me لا تُحسب فيه، ولها سقف مستقل: 120 نداءً في الساعة.

في باقة المجانية يمكنك إنشاء المفتاح، لكن نداءاته تُرفض: نقاط النهاية الخاضعة لسقف الساعة تعيد 403 والرمز API_REQUIRES_PAID_PLAN، ونقاط الذكاء الاصطناعي POST /api/v1/ai وPOST /api/v1/chat/completions وGET /api/v1/models وPOST /api/v1/design/system وPOST /api/v1/design/logo تعيد قبله 402 والرمز AI_PAID_ONLY. وحده GET /api/v1/me يجيب، ليعرض لبرنامجك الباقة وسبب منع الذكاء الاصطناعي. وإن نزلت باقتك إلى المجانية تبقى مفاتيحك في القائمة وتُرفض نداءاتها بالطريقة نفسها حتى تعود إلى باقة مدفوعة. قارن الباقات في الفوترة والباقات.

طلبات الذكاء الاصطناعي عبر المفتاح (المحادثة، وتوليد الكود، ونظام التصميم، والشعار) تُخصم من الحصة اليومية نفسها التي يستعملها المحرّر في المتصفح — راجع البناء بالذكاء الاصطناعي.

إذا تسرّب مفتاحك

ما يستطيعه من يحمل مفتاحك تحدده صلاحياته، فامنح كل مفتاح أقل ما يحتاجه. بالصلاحيات المحدَّدة مسبقاً يستطيع:

• قراءة المشاريع التي تملكها كاملة بملفاتها، وقراءة صفحاتها ونسخها (projects:read).
• إنشاء مشاريع، وإضافة صفحات تُكتب ملفاتها في المشروع، وحفظ نسخ (projects:write).
• استهلاك حصة الذكاء الاصطناعي بالمحادثة وتوليد الكود ونظام التصميم والشعار (ai:chat وdesign)، ونظام التصميم والشعار يكتبان في ملفات المشروع المسمّى. يستهلك سقف الساعة وحصة اليوم معاً، فقد يمنعك من استعمال الذكاء الاصطناعي في المحرّر حتى تتجدد الحصة.
• بناء مراحل القوالب وفحص توفّر النطاقات (templates وdomains:read).

وإن منحته publish يستطيع نشر مشاريعك وإلغاء نشرها. وإن منحته domains:write يستطيع تقديم طلبات شراء نطاقات أو نقلها باسمك — طلب يصل سعره بعد مراجعة الفريق، لا شراء فوري.

ما لا يستطيعه أي مفتاح:

• إنشاء مفاتيح أخرى أو عرضها أو إبطالها — إدارة المفاتيح بجلسة المتصفح وحدها، فلا يستطيع مفتاح مسروق أن يجدّد نفسه أو يوسّع صلاحياته.
• تسجيل الدخول إلى لوحتك، أو تغيير كلمة المرور أو البريد أو الفوترة.
• الوصول إلى مشاريع لا تملكها، ولو كنت متعاوناً مقبولاً فيها: المفتاح يرى مشاريع صاحبه وحده.
• إدارة الـWebhooks، أو حذف مشروع، أو استعادة نسخة سابقة، أو تعديل ملف بعينه — لا توجد نقطة نهاية بالمفتاح لذلك، وبقية مسارات المنصة تقبل جلسة المتصفح لا المفتاح.

ماذا تفعل: اضغط «إلغاء المفتاح» ثم «تأكيد الحذف» على المفتاح المسرَّب، وأنشئ مفتاحاً جديداً، وحدّثه في المكان الذي تستعمله فيه. تعرّف المفتاح المسرَّب من آخر أربعة محارف وتاريخ «آخر استخدام:». إن شككت أن حسابك نفسه مكشوف فغيّر كلمة المرور؛ ذلك يُبطل كل المفاتيح والجلسات دفعة واحدة.

لا تضع المفتاح في كود يعمل في متصفح الزائر أو في مستودع عام؛ استعمله من خادمك أو من سطر الأوامر. البداية في البدء السريع.

أسئلة شائعة

نسيت نسخ المفتاح، هل يمكن عرضه مرة أخرى؟

لا. الخادم لا يحفظ المفتاح نفسه. أبطل هذا المفتاح وأنشئ غيره.

هل يمكن إنشاء مفتاح للقراءة فقط أو بصلاحيات محددة؟

نعم. عند الإنشاء أزل التحديد عن كل الصلاحيات عدا projects:read، فيقرأ المفتاح مشاريعك ولا يعدّلها ولا ينشرها ولا يستهلك حصة الذكاء الاصطناعي. الصلاحيات لا تُعدَّل بعد الإنشاء.

لماذا يعود نداء مفتاحي الجديد بـ403؟

لأحد سببين، يميّزهما الحقل code في جسم الرد: API_REQUIRES_PAID_PLAN إن كان حسابك على باقة المجانية (الواجهة البرمجية للباقات المدفوعة فقط)، أو API_KEY_SCOPE_REQUIRED إن كان المفتاح لا يحمل صلاحية نقطة النهاية، والصلاحية الناقصة في scope.

هل يعمل المفتاح في Webhooks؟

الـWebhooks موجودة لكل مشروع في صفحة إعداداته، وتُدار بجلسة صاحب المشروع في المتصفح لا بالمفتاح، وتحتاج باقة تشمل الاستضافة. لكن نشر مشروع بمفتاح يحمل publish يطلق حدث project.published كما يطلقه النشر من المحرّر. راجع إعدادات المشروع ومرجع الواجهة البرمجية.