> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahlfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# المصادقة

> مفتاح API من نوع Bearer مع نطاقات صلاحيات. أنشئه في وحدة التحكم، وأرسله من خادمك، وبدّله مع فترة سماح.

يرسل كل استدعاء المفتاح في الترويسة `Authorization`:

```http theme={null}
Authorization: Bearer sk_a1b2c3d4_<64 characters>
```

يتكون المفتاح من `sk_` ثم 8 أحرف ثم شرطة سفلية ثم 64 حرفًا. تخزّن Sahl بصمة SHA-256 للمفتاح فقط، مع بادئة (`sk_a1b2c3d4`) لقائمة وحدة التحكم. يُعرض السر مرة واحدة عند إنشاء المفتاح أو تبديله، ولا يستطيع أي شخص في Sahl استرجاعه.

## إنشاء مفتاح

1. سجّل الدخول إلى وحدة التحكم عبر [app.sahlfinancial.com](https://app.sahlfinancial.com) بصفة مدير مساحة العمل أو مدير API، ببريد إلكتروني موثّق.
2. **Settings**، ثم **API Keys**، ثم **New key**.
3. امنحه اسمًا، مثل `production-backend` أو `sandbox-test`.
4. حدّد النطاقات. لا تُعرض إلا النطاقات التي يجوز لمساحة عملك امتلاكها.
5. اربطه اختياريًا بحساب خدمة Google (انظر أدناه).
6. **Create API Key**. انسخ السر من الشريط الظاهر. يُعرض مرة واحدة.

إذا ظهرت في النموذج عبارة "This workspace is not enabled for the partner KYC API, so its keys carry no scopes"، فـ[اطلب الوصول إلى بيئة الاختبار](https://sahlfinancial.com/contact?type=demo) لتفعيل واجهة الشركاء في مساحة عملك (تُفعَّل لكل مساحة عمل من قِبل Sahl). وطلب إنشاء مفتاح بنطاق `kyc:` في مساحة عمل غير مفعّلة يُرجع 403 `kyc_scope_not_allowed`.

لا يوجد مفتاح منفصل لبيئة الاختبار وآخر للإنتاج. يعمل مفتاح واحد في البيئتين، والحقل `environment` في كل استدعاء هو الذي يحدد البيئة. إذا أردت مفاتيح مختلفة لأنظمة مختلفة، فسمِّها وحدد نطاقاتها على هذا الأساس.

## النطاقات

| النطاق | يتيح |
| - | - |
| `kyc:extract` | `POST /v1/kyc/extract` |
| `kyc:verify` | `POST /v1/kyc/verify`, `POST /v1/kyc/assess` |
| `kyc:eid` | `POST /v1/kyc/eid`, `GET /v1/kyc/eid/{key}`, `GET /v1/kyc/eid/{key}/report` |

* هذه النطاقات الثلاثة هي الوحيدة. يُرفض أي نطاق خارج القائمة عند إنشاء المفتاح.
* لا يحمل المفتاح إلا النطاقات التي صدر بها، لذا لا يمكن استخدام مفتاح تسرّب لغرض ما في غرض آخر.
* يتطلب كل استدعاء `kyc:` أيضًا أن تكون مساحة العمل مفعّلة لواجهة الشركاء. والمفتاح الذي يحمل النطاق في مساحة عمل غير مفعّلة يحصل على 403 `kyc_scope_not_allowed`.
* امنح كل نظام الحد الأدنى مما يحتاج إليه. الخادم الذي يتحقق من الملفات فقط يحتاج إلى `kyc:verify` وليس `kyc:extract`، وهو النطاق الذي يستهلك القراءات.

## تبديل مفتاح

يُصدر التبديل مفتاحًا جديدًا ويُبقي القديم صالحًا خلال فترة سماح، فتتمكن من النشر دون انقطاع.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant You as You in the console
    participant Old as Old key
    participant New as New key
    participant App as Your servers
    You->>Old: Rotate, choose a grace period
    Old-->>You: New secret (shown once)
    Note over Old,New: Both keys work during the grace period
    You->>App: Deploy the new secret
    Note over Old: Grace period ends, old key returns 401 API key expired
    App->>New: Calls continue
```

1. **Settings, API Keys**، ابحث عن المفتاح، ثم انقر **Rotate**.
2. اختر المدة التي يبقى فيها المفتاح القديم صالحًا: بلا مدة، أو ساعة واحدة، أو 24 ساعة، أو 3 أيام، أو 7 أيام. تقبل واجهة البرمجة من 0 إلى 168 ساعة، والافتراضي 24.
3. انسخ السر الجديد وانشره.
4. عند انتهاء فترة السماح يُرجع المفتاح القديم 401 `API key expired`.

ما تضمنه الشيفرة:

* للمفتاح الجديد الاسم والنطاقات وحساب الخدمة المرتبط نفسها للمفتاح القديم. لا يمكن للتبديل توسيع الصلاحيات ولا تضييقها.
* تبديل مفتاح ما زال في فترة السماح يُرجع 409 `key_already_rotated`، فلا يؤدي تكرار الطلب إلى وجود عدة مفاتيح فعالة. استخدم المفتاح البديل، أو أنشئ مفتاحًا جديدًا.
* التبديل منحٌ جديد للنطاقات. ولا تستطيع مساحة عمل خرجت من قائمة الشركاء المسموح لهم إصدار مفاتيح `kyc:` جديدة عبر التبديل.
* تعرض قائمة المفاتيح "Grace" مع وقت الانتهاء للمفتاح الذي في فترة السماح.

## إبطال مفتاح

انقر **Revoke** في قائمة المفاتيح. يُرجع المفتاح المبطَل 401 `Invalid or revoked API key` ابتداءً من الاستدعاء التالي. أبطِل أي مفتاح يُحتمل أنه تسرّب، ثم أنشئ مفتاحًا جديدًا. والتبديل بدون فترة سماح يؤدي الغرض نفسه في خطوة واحدة ويمنحك بديلًا.

## ربط مفتاح بحساب خدمة

إذا كانت خوادمك تعمل على Google Cloud، يمكنك ربط المفتاح بحساب خدمة Google الذي تعمل به. عندئذٍ يجب أن يحمل كل استدعاء رمز هوية موقّعًا من Google لذلك الحساب في `X-Partner-Identity`، صادرًا للجمهور (audience) الظاهر في نموذج المفتاح. وبذلك لا يفيد المفتاح المسرَّب وحده.

| القاعدة | القيمة |
| - | - |
| الصيغة | `name@project.iam.gserviceaccount.com`. يُرفض حساب Google الشخصي. |
| عدة حسابات | افصل بينها بفواصل، مثل حساب الاختبار المرحلي والإنتاج. بحد أقصى 255 حرفًا في المجموع. |
| رمز مفقود أو غير صالح | 401 `Partner identity could not be verified` |

لا تستطيع ساحة تجربة API (playground) إرسال هذه الترويسة، فلا تربط مفتاحًا تريد تجربته فيها.

## الأخطاء

| الحالة | `detail` | السبب |
| - | - | - |
| 401 | `Missing API key` | لا توجد ترويسة `Authorization`، أو قيمتها فارغة، أو مخطط غير `Bearer`. |
| 401 | `Invalid or revoked API key` | مفتاح خاطئ، أو مشوَّه، أو مبطَل. |
| 401 | `API key expired` | مفتاح مبدَّل انتهت فترة سماحه. |
| 401 | `Partner identity could not be verified` | المفتاح مرتبط بحساب خدمة، ورمز الهوية مفقود أو منتهي الصلاحية أو صادر لجمهور آخر أو لحساب آخر. |
| 403 | `API key lacks the kyc:verify scope` (string) | لا يحمل المفتاح النطاق المطلوب لنقطة النهاية هذه. |
| 403 | `{"code": "kyc_scope_not_allowed", ...}` | مساحة العمل غير مفعّلة لواجهة KYC للشركاء. |
| 403 | `{"code": "direct_access_refused", ...}` | استدعيت العنوان الداخلي لـ Sahl. استدعِ `https://app.sahlfinancial.com/api`. |

عالج نقص النطاق بإنشاء مفتاح يحمله. يجري فحص النطاق قبل فحص مساحة العمل، لذا يحصل المفتاح الذي لا يحمل النطاق على الصيغة النصية حتى لو كانت مساحة العمل غير مفعّلة.

## حماية المفاتيح

* استدعِ واجهة البرمجة من خادمك فقط. لا تضع مفتاحًا أبدًا في متصفح أو تطبيق جوال أو مستودع شيفرة.
* احتفظ به في مدير أسرار أو في متغير بيئة مثل `SAHL_API_KEY`.
* مفتاح واحد لكل نظام، لتتمكن من إبطال أحدها دون إيقاف البقية.
* راقب **Developers, Call log** في وحدة التحكم: تُعرض فيه استدعاءات كل مفتاح وحالتها وزمن استجابتها، وتُظهر قائمة المفاتيح وقت آخر استدعاء لكل مفتاح.
* ترسل ساحة تجربة الوثائق الطلب من متصفحك مباشرة إلى واجهة Sahl. لا يمرّره هذا الموقع عبر وسيط ولا يخزّن مفتاحك. ومع ذلك الصق مفتاحًا أُنشئ للاختبار، وأبطله عند الانتهاء.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.