رموز الواجهة البرمجية

يتيح الرمز البرمجي لنظام آخر أن ينادي واجهة X-Radius نيابةً عن مدير، بلا وضع كلمة مرور ذلك الشخص في ملف إعداد وبلا منح السكربت كامل صلاحياته.

ما الرمز

الرمز يخصّ مديرًا واحدًا بالضبط ويُنشأ من المطوّر ← رموز الواجهة البرمجية. ويبدأ بـ xrt_، وهي بادئة لا يصدرها شيء آخر في النظام، فيسهل العثور عليه في ملف إعداد مسرَّب أو بأداة فحص أسرار.

عامله كما تعامل كلمة مرور تمامًا. فمن يحمله يستطيع التصرف باسم صاحبه، ضمن حدود الرمز، حتى يُبطَل.

العنوان الأساسي

https://<اسم-مستأجرك>.<نطاق-النسخة>/api/v1

استخدم المضيف الذي تراه في المتصفح وأنت داخل على اللوحة. وصفحة مرجع الواجهة داخل اللوحة تطبع عنوانك الأساسي بالضبط لهذا السبب.

فنداء عنوان النسخة نفسه لا يحدّد مستأجرًا، فيعود كل طلب فارغًا أو غير مصرَّح — ويبدو ذلك تمامًا كرمز خاطئ. فإن فشل نداؤك الأول فتحقق من المضيف قبل أي شيء آخر.

المصادقة والردود

أرسل الرمز مع كل طلب. لا خطوة دخول ولا جلسة تُجدَّد.

curl -s https://acme.example.com/api/v1/auth/me \
  -H "Authorization: Bearer $XRADIUS_TOKEN"

يعيد /auth/me من يتصرف الرمز باسمه والقائمة الدقيقة للصلاحيات التي يحملها. فإن نجح هذا النداء فالباقي مسألة اختيار نقاط النهاية.

والنجاح يغلّف الحمولة في data، وتضيف القائمة كتلة meta بالترقيم:

{ "data": [], "meta": { "page": 1, "page_size": 25, "total": 812 } }

والأخطاء تستخدم شكلًا واحدًا دائمًا، فيه code ورسالة للبشر وrequest_id تذكره عند طلب المساعدة وdetails.reason يقرؤه البرنامج. والطوابع الزمنية على السلك بصيغة yyyy-MM-dd HH:mm:ss بتوقيت UTC.

ما يستطيع الرمز فعله

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

• لا يستطيع الرمز أن يفعل أكثر من صاحبه. فتأشير صلاحية لا تحملها لا أثر له: النطاق سقف لا منحة.
• يتتبّع صاحبه حيًا وفي الاتجاهين. فإن خُفِّضت صلاحيات صاحبه انكمش الرمز في الثانية نفسها.
• الرمز المقيَّد مقيَّد حتى لمدير عام. فالرمز المحدود بـ"عرض المشتركين" ليس رمز إدارة، أيًا كان من أنشأه.

اختر الوصول الكامل حين يكون التكامل هو أنت داخل سكربت. واختر المقيَّد، بأصغر مجموعة تكفي، لما عدا ذلك.

ما لا يستطيع الرمز فعله أبدًا

بعض الواجهات ترفض الرموز رفضًا قاطعًا:

• بيانات اعتماد الحساب — كلمة المرور والتحقق بخطوتين والجلسات. فالرمز الذي يستطيع تغيير كلمة مرور صاحبه أداة استيلاء على الحساب.
• إدارة الرموز نفسها. وإلا استطاع الرمز توسيع نطاقه بنفسه.
• الدخول باسم مدير آخر، إذ يتيح للرمز القفز إلى حساب أقوى.

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

إدارة الرموز

إظهار يعرض السرّ من جديد ويطلب كلمة مرورك، ويُكتب في سجل التدقيق. وتدوير يصدر سرًّا جديدًا فورًا ويقتل القديم بلا فترة تداخل، لأن الحالة التي تهمّ هي التسريب. وتعطيل مفتاح إيقاف قابل للرجوع. وإبطال نهائي، ويبقى السجل في القائمة لترى ما فعله الرمز.

وللتدوير المخطَّط: أنشئ رمزًا ثانيًا، وانقل التكامل إليه، وتأكد أنه يعمل، ثم أبطل الأول. أما التدوير فهو مسار الطوارئ.

إن لم تنجح

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