المصادقة

مفاتيح API (موصى بها للتكاملات)

مفتاح API رمز وصول شخصي مرتبط بعضو في حسابك.

أنشئ مفتاحًا في الإعدادات ← الإضافات ← مفاتيح RolChat API. يُعرض السر مرة واحدة؛ وبعدها لا تظهر إلا أحرفه العشرة الأولى، ولا يخزّن RolChat إلا تجزئة SHA-256.
الصيغة: rcp_ متبوعة بـ 32 بايت عشوائية بترميز base64url، نحو 45 حرفًا إجمالًا. تجعل البادئة المفتاح قابلًا للتمييز في السجلات ومختلفًا عن رمز الجلسة.
النطاقات: تُختار من كتالوج ثابت من القدرات عند إنشاء المفتاح. لا يستطيع المفتاح أبدًا فعل أكثر مما يستطيعه العضو الذي أنشأه: في كل استدعاء يُفحص الشرطان معًا، أن تكون القدرة ضمن نطاقات المفتاح وأن يظل العضو يملكها. قلّص دور العضو فيتقلص المفتاح معه.
مدة الصلاحية: لا تنتهي صلاحية المفاتيح من تلقاء نفسها. ألغِ المفتاح من صفحة الملف الشخصي أو عبر DELETE /api/v1/tokens/:id؛ ويسري الإلغاء فورًا. لا يوجد تدوير في المكان: ألغِ المفتاح وأنشئ مفتاحًا جديدًا.
يُكتب الإنشاء والإلغاء في سجل التدقيق.

أرسله كرمز bearer - لا توجد ترويسة منفصلة لمفتاح API:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

الطلبات بمفتاح API للإضافات محدودة بـ 300 طلب في الدقيقة.

جلسات JWT

يسجّل تطبيق الويب وحزم SDK للجوال الدخول بالبريد الإلكتروني وكلمة المرور (أو Google أو Apple) ويتلقيان زوجًا من الرموز.

الرمز	مدة الصلاحية	ملاحظات
رمز الوصول	15 دقيقة	RS256، يُتحقق منه مقابل JWKS على `/.well-known/jwks.json`
رمز التحديث	30 يومًا	يُدوَّر عند كل تحديث؛ وإعادة استخدام رمز مُدوَّر تلغي السلسلة كلها

المطالبات: sub (المستخدم)، وacc (الحساب)، وrl (الدور)، وsts (المواقع المسموح بها) للأدوار المحددة بموقع.

POST /auth/login و/auth/refresh و/auth/swap-company و/auth/logout هي نقاط النهاية الوحيدة في مسار المصادقة التي يجب ألا تحمل الترويسة X-Account-Id الموصوفة أدناه.

الترويسة `X-Account-Id`

كل طلب مصادَق عليه، باستثناء الأربعة أعلاه، يجب أن يحمل الحساب الذي يتصرف باسمه:

X-Account-Id: <account uuid>

يتحقق الخادم من أن الترويسة تساوي المطالبة acc في الرمز (أو حساب مفتاح API). غياب الترويسة يعطي 400 missing_required_header؛ وعدم التطابق يعطي 403 account_context_mismatch. توجد الترويسة كي لا يتمكن خلل في العميل أو رمز مُعاد إرساله من قراءة بيانات مستأجر آخر بصمت أبدًا: يُرفض عدم التطابق قبل تنفيذ أي استعلام، ويمكن نسبة كل سطر في السجل إلى حساب من دون فك ترميز الرمز.

المستخدمون متعددو الشركات

يمكن للشخص الواحد الانتماء إلى عدة شركات. لكل شركة رمزها الخاص (بمطالبة acc خاصة بها). للتبديل:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

يجب أن يكون الهدف ضمن available_companies الخاصة بالمستدعي (تُعاد عند تسجيل الدخول)، وإلا فالنتيجة 403 forbidden. الاستجابة زوج جديد من رمزي الوصول والتحديث بنطاق الهدف؛ ويُلغى رمز التحديث القديم ويُكتب حدث تدقيق auth.account.swapped.