مفاتيح API

يسرد GET /keys كل مفتاح يستطيع المستدعي رؤيته، الأحدث أولًا وصفحةً صفحة، مع حالته ونطاقاته ودوره ونطاق إرساله وآخر استخدام له ومن أنشأه ومن غيّره آخر مرة. ويقرأ GET /keys/{id} واحدًا. لا تعيد أي قراءة سرًّا أبدًا: maskedKey يكفي للتمييز بين مفتاحين. كلاهما يتطلب keys:read.

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —ينشئ POST /keys مفتاحًا ويعيد سرّه في token مرة واحدة. إن لم تُحدَّد، فالنطاق emails:send والدور ونطاق الإرسال وانتهاء الصلاحية هي تلك الخاصة بالمستدعي.
• —يعيد PATCH /keys/{id} تسمية المفتاح ويستبدل نطاقاته أو نطاق إرساله ويوقفه ويشغّله بـenabled. الإيقاف هو الخيار القابل للتراجع: يحتفظ المفتاح بكل شيء ويُرفض بـinactive_api_key حتى يُشغَّل من جديد.
• —يمنح POST /keys/{id}/rotate المفتاح سرًّا جديدًا ويعيده مرة واحدة. يتوقف السرّ القديم عن العمل لحظة عودة الاستدعاء.
• —يُخرج POST /keys/{id}/revoke المفتاح من الخدمة نهائيًا، مع reason اختياري. ثم يزيله DELETE /keys/{id} من القائمة ويحتفظ بسجلّه.
• —يتطلب كل منها keys:manage. وتدوير المفتاح المستدعي نفسه يعمل أيضًا بـkeys:write، تمامًا مثل POST /keys/self/rotate.

يُتحقق من كل تغيير مقابل المفتاح الذي يجريه. المفتاح الذي سينتهي خارج المستدعي على أي محور يُرفض بـ403 beyond_caller_authority، ويسمّي param المحور:

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

تطلب وحدة التحكم منك التحقق من نفسك مجددًا قبل أن تنشئ مفتاحًا أو تدوّره. لا يمكن طلب ذلك من استدعاء يجري بمفتاح، لذا فإن keys:manage اعتماد يصنع اعتمادات: المفتاح المسرَّب الذي يحمله يستطيع إنشاء مفاتيح خاصة به، حتى حدود وصوله، تظل تعمل بعد إبطاله.

• —امنح keys:manage فقط لأتمتة عملها إصدار المفاتيح، ولا تمنحه أبدًا لمفتاح يرسل البريد.
• —ضيّق ذلك المفتاح: دور ونطاق إرسال وانتهاء صلاحية. كل ما ينشئه يرث الثلاثة ولا يستطيع تجاوزها أبدًا.
• —راقب GET /keys/activity. كل مفتاح ينشئه أو يغيّره أو يبطله يُسجَّل باسمه، لذا يظهر التسريب في صورة مفاتيح لم تتوقعها.
• —يكشف keys:read سجل الطلبات، بما فيه عناوين IP ووكلاء المستخدم. عامله كصلاحية تدقيق.

يقرأ GET /keys/requests وGET /keys/{id}/requests كل استدعاء موثَّق أجراه مفتاح، الأحدث أولًا: الطريقة والمسار والحالة ورمز الخطأ والمدة وIP ووكيل المستخدم، ولا يقرأ أبدًا محتوى أو سلسلة استعلام. keyIds وfailedOnly وsince وuntil هي المرشّحات التي تقدّمها وحدة التحكم. ويقرأ GET /keys/activity وGET /keys/{id}/activity ما جرى للمفاتيح، ويسمّي actor من فعل ذلك، بصيغة @username أو API key <name>. لا يُحذف شيء، ويحتفظ المفتاح المحذوف بسجلّه.