API

المصادقة

نوع واحد من بيانات الاعتماد، والطرق التي يُرفض بها الطلب.

الترويسة

عنوان الـ URL الأساسي هو api.openemail.uk. وكل طلب يحمل المفتاح في ترويسة Authorization.

Authorization

Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…

لا شيء آخر يصادِق هنا. فكعكة الجلسة ورمز الجلسة كلاهما يُرفض بـ invalid_credential_type، وهو يسمّي بيانات الاعتماد التي ينبغي إرسالها بدلًا من أن يتركك تخمّن أمام 401 مجرّد.

التحقق من أن مفتاحًا يعمل

GET /ping هو اختبار التشغيل السريع: لا يحتاج أي نطاق ويخبرك ما هو المفتاح.

curl

curl "$OE/ping" -H "$AUTH"

الاستجابة

{  "ok": true,  "keyId": "4c1b257a66287fd113bd89d0",  "mode": "live",  "scopes": ["emails:send", "emails:read"],  "roleId": null,  "grantedScopes": ["emails:send", "emails:read"],  "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}

إن نجح هذا وأعاد شيء آخر 401، فالمشكلة في النطاق لا في المفتاح.

scopes هي القائمة الفعلية وهي وحدها التي تخوّل أي شيء. أما grantedScopes فهي ما صدر به المفتاح، ولا يختلف الاثنان إلا حين يحدّ دورٌ ما المفتاحَ. وصفحة النطاقات تشرح ذلك التقاطع. وقيمة roleId تساوي null تعني ألا سقف هناك، وهو أوسع ما يبلغه مفتاح.

معرفة ما يمكن لمفتاح أن يرسل باسمه

GET /addresses هو الجواب عن 403 لم تكن تتوقعه.

curl

curl "$OE/addresses" -H "$AUTH"

الاستجابة

{  "object": "list",  "unrestricted": false,  "data": [    { "object": "address", "address": "[email protected]", "enabled": true, "canSend": true },    { "object": "address", "address": "[email protected]", "enabled": true, "canSend": false }  ],  "domains": [    { "domain": "acme.com", "receivingVerified": true, "sendingVerified": true, "catchAll": false }  ]}

canSend: false له ثلاثة أسباب: العنوان مطفأ، أو نطاق الإرسال الخاص بالمفتاح لا يشمله (فلا نطاقه ولا العنوان نفسه مدرج على المفتاح)، أو النطاق لا يستطيع التوقيع بعد. ويميّز enabled على العنوان وsendingVerified على نطاقه بين هذه الحالات، وهذا هو معظم وقت التنقيح الذي توفّره هذه النقطة. فقد يكون النطاق موثّقًا للاستقبال وعاجزًا عن الإرسال.

unrestricted: true تعني قبول أي جزء محلي على نطاق موثّق، بما في ذلك أجزاء لم ينشئها أحد بعد.

كيف يُرفض مفتاح

الرمز	المعنى
missing_api_key	لا توجد ترويسة Authorization إطلاقًا.
invalid_credential_type	كعكة أو رمز جلسة. أرسِل مفتاح API.
invalid_api_key	ليس مفتاحًا أصدرناه، أو أن السر غير مطابق.
revoked_api_key	صدر من هنا ثم أُبطل. مميّز عن غيره عن قصد. فهو الفرق بين إصلاح يستغرق خمس دقائق وآخر يستغرق بعد ظهيرة كاملة.
expired_api_key	صدر من هنا ثم انتهت صلاحيته.
insufficient_scope	مفتاح حقيقي، لكن بلا النطاق الذي تحتاجه هذه النقطة.

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

التدوير هو الطريقة الأخرى لإحالة سرٍّ إلى التقاعد. فهو يسكّ سرًّا جديدًا للمفتاح نفسه، بحيث يستمر المعرّف والاسم والنطاقات والدور ونطاق الإرسال وكل صفوف الطلبات والنشاط؛ ولا يتغيّر سوى السر. ويتوقف القديم عن العمل لحظة اكتمال التدوير، بلا نافذة تداخل، ويُعرض البديل مرة واحدة. ومن وحدة التحكم تجده في القائمة نفسها التي تضم Revoke ويطلب منك إعادة التحقق أولًا. كما يستطيع مفتاح يحمل keys:write أن يدوّر نفسه عبر POST /keys/self/rotate، وهي الطريقة التي يدوّر بها تكامل ما مفتاحه وفق جدول دون أن يفتح أحد وحدة التحكم.