قاعدة المعرفة
مفاتيح API
مفتاح لكل مهمة، مقيّد بالصلاحيات والمرسِلين الذين يحتاجهم، مع تسجيل كل استدعاء.
التفاصيل
- تُنشأ من الإعدادات ← مفاتيح API، في مساحة عمل تملكها. يُعرض السرّ مرة واحدة، وكل مفتاح هو مفتاح oe_live_.
- يحمل المفتاح الصلاحيات التي تختارها فقط، ويبدأ المفتاح الجديد بـ emails:send. ويمكن أن يحمل دوراً، وهو سقف لا منحة ثانية: يعيد GET /ping الصلاحيات التي يسمّيها المفتاح وتلك التي تركها له الدور، فيكون لرمز 403 على صلاحية يحملها المفتاح بوضوح سبب ظاهر.
- يسمّي نطاق الإرسال حتى 25 نطاقاً كاملاً و50 عنواناً منفرداً. والنطاق الكامل يشمل أيضاً العناوين المضافة إليه لاحقاً، والمرسل من خارج القائمة يُرفض بـ 403.
- انتهاء صلاحية اختياري يجعل المفتاح ينتهي من تلقاء نفسه، حتى عشر سنوات مقدماً.
- التدوير يبدّل السرّ فقط: يستمر المعرّف والصلاحيات ونطاق الإرسال وسجل الطلبات، ويتوقف السرّ القديم لحظة إنشاء الجديد. والمفتاح الذي يحمل keys:write يستطيع تدوير نفسه عبر الـ API. والإبطال تحديث لا حذف، لذا يُقال لأي استدعاء لاحق revoked_api_key.
- يُسجَّل كل استدعاء موثَّق بطريقته ومساره وحالته ورمز خطئه ومدته وعنوان IP ووكيل المستخدم، ولا يُسجَّل المحتوى أو معاملات الاستعلام أبداً. تعرض صفحة المفتاح ذلك في التحليلات والنشاط والطلبات، مع أكثر المسارات استخداماً وعدد مرات فشلها ووسيط زمن استجابتها، وتشمل العروض نفسها عدة مفاتيح معاً. يُحتفظ بالسجل ولا يُقتطع.
- كل ما تفعله الصفحة متاح أيضًا عبر API وSDK: يقرأ GET /keys وGET /keys/{id} المفاتيح دون أسرارها، وينشئ POST /keys مفتاحًا، ويعيد PATCH /keys/{id} تسميته ويغيّر نطاقاته أو نطاق الإرسال ويوقفه ويعيد تشغيله، وتفعل rotate وrevoke وdelete ما تقوله أسماؤها. ويُقرأ سجل الطلبات والنشاط بالطريقة نفسها، لمفتاح واحد أو لها كلها، بمرشّحات الصفحة. تتطلب القراءة keys:read ويتطلب كل تغيير keys:manage، وهما نطاقان لا يحملهما أي مفتاح ما لم يمنحه إياهما أحد. ويقرأ خادم MCP السجل والنشاط كذلك، باسم listApiKeyRequests وlistApiKeyActivity.
- لا ينشئ المفتاح أبدًا مفتاحًا أوسع منه ولا يصل إليه: يجب أن تبقى نطاقاته ودوره وانتهاء صلاحيته ووضعه ونطاق إرساله كلها داخل المفتاح الذي يجري الاستدعاء. لا يمكن تطبيق التحقق الإضافي على استدعاء يجري بمفتاح، لذا فإن keys:manage اعتماد يصنع اعتمادات. امنحه فقط لأتمتة تصدر المفاتيح، بدور ونطاق إرسال وانتهاء صلاحية خاصة بها، وراقب تبويب النشاط حيث يُسجَّل كل ما تفعله باسمها.
- ما ينقص: لا يمكن ربط مفتاح بعناوين IP، ولا يمكن إنشاء مفتاح في وضع الاختبار.