المصادقة

نوعان من بيانات الاعتماد، يُستخدمان بالتتابع: مفتاح API تديره في التطبيق، ورمز وصول قصير العمر تحصل عليه منه.

مفاتيح API

تُنشأ من Vault → API Keys → Add في تطبيق OneGuard. المفتاح:

• يبدأ بـ og_ ويظهر مرة واحدة فقط — يخزّن التطبيق تجزئته (hash) فقط، فلا يمكن استرجاع مفتاح مفقود، بل إلغاؤه واستبداله فقط.
• له صلاحية قراءة أو كتابة، تُفحص في كل طلب. مفتاح القراءة يسرد ويجلب؛ ومفتاح الكتابة يمكنه أيضًا الإنشاء والتغيير والحذف.
• له تاريخ انتهاء تحدّده عند إنشائه.
• يمكن تدويره أو إيقافه من شاشة API Keys نفسها، دون التأثير على مفاتيح أخرى.

لا يُرسَل المفتاح أبدًا في أي طلب سوى الطلب التالي.

مبادلة مفتاح برمز

curl -s https://api.oneguard.one/v1/auth/token \
  -X POST \
  -H "Authorization: Bearer og_your_key"

{
  "statusCode": 200,
  "errorCode": null,
  "message": null,
  "data": {
    "access_token": "ogt_eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-09-23T15:04:05.000Z"
  }
}

يُقرأ المفتاح من ترويسة Authorization فقط — لا أبدًا من نص الطلب أو سلسلة الاستعلام. كل طلب /v1 آخر يستخدم رمز ogt_... الناتج بالطريقة نفسها:

curl -s https://api.oneguard.one/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

مدة صلاحية الرمز

يبقى رمز الوصول صالحًا لعدد ثوانٍ يساويه expires_in (حاليًا 3600، أي 60 دقيقة) بدءًا من expires_at. لا توجد نقطة نهاية منفصلة للتجديد — عندما ينتهي الرمز، بادل مفتاح API مرة أخرى بالطريقة نفسها التي فعلتها أول مرة. الاستجابة رمز جديد تمامًا في كل مرة، فلا شيء يُبطَل بجلب رمز جديد مبكرًا.

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

ماذا يعني 401 أثناء الجلسة

{
  "statusCode": 401,
  "errorCode": "unauthorized",
  "message": "...",
  "data": null
}

مع ترويسة WWW-Authenticate: Bearer. يحدث هذا عندما ينتهي الرمز، أو يُعطَّل المفتاح وراءه أو يُحذف، أو تكون ترويسة Authorization مفقودة أو غير صحيحة الصياغة. الحل دائمًا نفسه: بادل المفتاح مرة أخرى للحصول على رمز جديد.

تدوير مفتاح وإلغاؤه

يتم تجديد المفتاح أو تعطيله من Vault → API Keys في التطبيق، وليس عبر هذه الواجهة.

• التعطيل: تتوقف الرموز الصادرة سابقًا عن العمل خلال نحو 30 ثانية (يخزّن الخادم حالة المفتاح مؤقتًا لتفادي الاستعلام عن قاعدة البيانات في كل طلب).
• التجديد: يصدر قيمة og_... جديدة. الرمز الذي بودل قبل التجديد مباشرة يبقى يعمل لفترة سماح قصيرة بعده، فلا ينقطع طلب قيد التنفيذ أثناء التدوير — لكن بادل المفتاح الجديد وانتقل إليه بأسرع ما يمكن.

في الحالتين، لا يُحذف المفتاح نفسه بهذا الإجراء — بل يُعطَّل أو يُستبدل، ويبقى ظاهرًا (وقابلًا لإعادة التفعيل في حال التعطيل) من Vault → API Keys.