المصادقة

لا تحتاج البيانات العامة إلى بيانات اعتماد. أما أي عمل يُنجَز باسم مؤسسة فيحتاج إلى بيانات اعتماد تخص تلك المؤسسة: مفتاح API، أو رمز وصول من عميل OAuth. ويُصدِر كليهما مالكو المؤسسة ومديروها من لوحة التحكم.

مفاتيح API

يبدو مفتاح API على هذا الشكل: brl_api_<id>_<secret>. أرسله رمزًا من نوع Bearer:

GET /v1/org/deals HTTP/1.1
Host: api.birlesa.com
Authorization: Bearer brl_api_01a1...

مدة الصلاحية: من يوم واحد إلى 366 يومًا (90 يومًا افتراضيًا). خطّط للتدوير: أصدِر المفتاح الجديد، وانشره، ثم ألغِ القديم.
يُعرض مرة واحدة: لا نخزّن إلا بصمة مجزّأة (hash) مُضافًا إليها سرّ إضافي (pepper).
الإلغاء يسري خلال دقيقة في كل مكان، وفورًا على الإجراءات وعلى قراءة سجلات المؤسسة.
من يغادرون: عندما يغادر شخص المؤسسة أو يتوقف عن كونه مديرًا، تُلغى المفاتيح وعملاء OAuth الذين أنشأهم، وتُوقَف خطافات الويب التي أعدّها.

الصلاحيات

يقرأ المفتاح البيانات العامة. أما ما يُسمح له به غير ذلك فيُحدَّد عند إصداره:

الصلاحية	ما تتيحه
`needs:write`	نشر احتياجات المؤسسة (عبر REST وعبر أداة `submit_need` في خادم MCP)
`rfqs:send`	طلب عروض أسعار من الموردين على احتياجات المؤسسة المفتوحة
`org:read`	قراءة سجلات المؤسسة الخاصة تحت `/v1/org/...`
`signals:read`	لشركاء الائتمان: قراءة إشارات المخاطر للشركات التي أعطت موافقتها
`data:read`	قراءة منتجات البيانات التي أبرمت المؤسسة عقدًا بشأنها

امنح كل تكامل ما يستخدمه فقط. المفتاح الذي يفتقر إلى صلاحية يتلقى 403 مع الرمز no_org_read (أو ما يقابله للإجراء المعني).

بيانات اعتماد العميل في OAuth 2.0

للتكاملات الآلية التي لا ينبغي أن تحمل مفتاحًا طويل الأمد، أنشئ عميل OAuth في لوحة التحكم. ستحصل على client_id (معرّف UUID) وclient_secret (brl_ocs_...، يُعرض مرة واحدة). استبدِلهما برمز وصول (RFC 6749 §4.4(يُفتح في علامة تبويب جديدة)):

POST /oauth/token HTTP/1.1
Host: api.birlesa.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=org:read

{"access_token": "brl_api_01a1...", "token_type": "Bearer", "expires_in": 3600, "scope": "org:read"}

رمز الوصول مفتاح API صالح لساعة واحدة. استخدمه تمامًا كما تستخدم المفتاح.
يضيّق scope صلاحيات العميل؛ اتركه لتحصل عليها كلها. وطلب أكثر مما يملكه العميل يفشل بالرمز invalid_scope.
يمكن للعميل أيضًا إرسال client_id وclient_secret في نص النموذج بدلًا من HTTP Basic.
لا يكون للعميل أكثر من 20 رمزًا ساريًا في وقت واحد؛ وأي رمز جديد بعد ذلك يُلغي أقدمها. احتفظ بالرمز مؤقتًا حتى قُبيل انقضاء expires_in، ولا تطلب رمزًا جديدًا مع كل استدعاء.
إلغاء العميل يُلغي رموزه.
تتبع الأخطاء RFC 6749: invalid_client (401)، وinvalid_scope، وunsupported_grant_type، وinvalid_request (400)، وslow_down (429). ولا تُخزَّن الاستجابات مؤقتًا أبدًا (Cache-Control: no-store).

أشخاص، لا مفاتيح

تُدخل لوحة الأعضاء ووحدة تحكم الموظفين الأشخاصَ عبر مزوّد الهوية الخاص بـ Birlesa. رموزهم ليست بيانات اعتماد للواجهة البرمجية، ومفاتيح API لا تفتح لوحة التحكم. ورسائل المحادثات وأدلة النزاعات متاحة فقط للأشخاص في لوحة التحكم.