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

# المصادقة

> طرق مصادقة API، وإدارة المفاتيح، وأفضل ممارسات الأمان.

تدعم Truthlocks طرق مصادقة متعددة لتأمين الوصول إلى واجهة برمجة التطبيقات (API). يغطي هذا الدليل مفاتيح API، ورموز JWT، وأفضل ممارسات الأمان.

## طرق المصادقة

> [card] مفاتيح API
>
> بيانات اعتماد طويلة الأمد للاتصال من خادم إلى خادم. موصى بها لـ
> خدمات الواجهة الخلفية.

> [card] رموز الحامل (JWT)
>
> رموز قصيرة الأجل للمستخدمين المصادق عليهم. مثالية لتطبيقات الواجهة الأمامية
> وسياق المستخدم.

## مفاتيح API

لدى Truthlocks نوعان من مفاتيح API اعتمادًا على كيفية استخدامك للمنصة:

| النوع | البادئة | تم الإنشاء من | حالة الاستخدام |
| :- | :- | :- | :- |
| **مفتاح المستأجر** | `tl_live_` / `tl_test_` | [Console](https://console.truthlocks.com) | تكاملات من خادم إلى خادم، سير عمل المؤسسات |
| **مفتاح المستهلك** | `tlk_` | [بوابة Verify](https://verify.truthlocks.com) | وصول API شخصي لحماية المحتوى والتحقق |

### تمرير مفتاحك

قم بتضمين مفتاح API الخاص بك باستخدام أحد هذين الرأسين:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "X-API-Key: tl_live_your_api_key"
```

يمكنك أيضًا استخدام رأس `Authorization` مع مخطط `ApiKey`:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "Authorization: ApiKey tl_live_your_api_key"
```

تُصادق هذه التنسيقات نقاط نهاية ممكّنة بمفتاح API. تتطلب بعض العمليات رمز حامل مستخدم وفحوصات دور، ولا تحتاج نقاط نهاية الصحة العامة إلى أي منهما. `X-API-Key` أكثر شيوعًا في الأمثلة في جميع أنحاء هذا التوثيق.

## مفاتيح API للمستأجر

مفاتيح المستأجر هي طريقة المصادقة الأساسية للمؤسسات التي تستخدم Truthlocks. وهي محددة النطاق لمستأجر وتدعم أذونات دقيقة.

### هيكل المفتاح

```text theme={null}
tl_live_abc123def456gh789ijklmnopqrstuv
│  │    │
│  │    └── 32-character random identifier
│  └── Environment: test | live
└── Prefix: tl (Truthlocks)
```

### النطاقات

يمكن تقييد مفاتيح API للمستأجرين على أذونات محددة:

| النطاق | الأذونات |
| - | - |
| `attestations:mint` | إنشاء إشهادات جديدة |
| `attestations:read` | قراءة تفاصيل الإشهاد وحزم الإثبات |
| `attestations:revoke` | إلغاء التصديقات |
| `issuers:read` | عرض معلومات المُصدر |
| `issuers:write` | إنشاء وإدارة المُصدرين |
| `users:read` | عرض المستخدمين والأدوار |
| `users:write` | دعوة المستخدمين، إدارة الأدوار |
| `audit:read` | استعلام سجلات التدقيق |

> [!NOTE]
>
> **مبدأ الحد الأدنى من الامتيازات:** امنح فقط النطاقات التي يحتاجها تطبيقك.
> يحتاجها بالفعل. يجب ألا يحتوي المفتاح الذي يحتوي على `attestations:mint` فقط على
> `users:write`.

### إنشاء مفتاح مستأجر

#### عبر وحدة التحكم

1. انتقل إلى [console.truthlocks.com/api-keys](https://console.truthlocks.com/api-keys)
2. انقر على "إنشاء مفتاح API"
3. أدخل اسمًا وصفيًا (على سبيل المثال، "الواجهة الخلفية للإنتاج")
4. حدد البيئة (الإنتاج أو بيئة الاختبار) والنطاقات المطلوبة
5. انسخ المفتاح فورًا — لن يتم عرضه مرة أخرى

#### عبر واجهة برمجة التطبيقات

```bash Request theme={null}
curl -X POST https://api.truthlocks.com/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "scopes": ["attestations:mint", "attestations:read", "issuers:read"]
  }'
```

```json Response theme={null}
{
  "id": "key-uuid",
  "name": "Production Backend",
  "prefix": "tl_live_abc",
  "secret": "tl_live_abc123def456gh789ijklmnopqrstuv",
  "scopes": ["attestations:mint", "attestations:read", "issuers:read"],
  "created_at": "2026-01-13T12:00:00Z"
}
```

> [!WARNING]
>
> **هام:** يتم إرجاع حقل `secret` مرة واحدة فقط عند الإنشاء. قم بتخزينه.
> على الفور في مدير الأسرار.

## مفاتيح API للمستهلك

تسمح مفاتيح المستهلك للمستخدمين الفرديين بالوصول إلى واجهات برمجة تطبيقات الحماية والتحقق برمجيًا — على سبيل المثال، لسك الشهادات من خط أنابيب CI أو دمج حماية المحتوى في أدواتك الخاصة.

### التفاصيل الرئيسية

* يدعم كل حساب ما يصل إلى **5 مفاتيح نشطة**.
* تنتهي صلاحية المفاتيح تلقائيًا بعد **90 يومًا**.
* لا يمكن إعادة تنشيط المفاتيح الملغاة أو منتهية الصلاحية — قم بإنشاء مفتاح جديد بدلاً من ذلك.

### نطاقات ثابتة

يتم إصدار مفاتيح المستهلك بمجموعة ثابتة من النطاقات لا يمكن تخصيصها:

| النطاق | الأذونات |
| :- | :- |
| `consumer:read` | قراءة ملف تعريف المستهلك الخاص بك وإعداداته |
| `consumer:write` | تحديث ملف تعريف المستهلك والإعدادات الخاصة بك |
| `attestations:mint` | سك شهادات جديدة |
| `attestations:read` | قراءة تصديقاتك |
| `verify:read` | التحقق من التصديقات |

### إنشاء مفتاح مستهلك

**1. فتح الإعدادات**

في الشريط الجانبي لبوابة التحقق، انتقل إلى **الإعدادات > مفاتيح API**.

**2. إنشاء مفتاح**

انقر فوق **إنشاء مفتاح API**، وأدخل اسمًا وصفيًا، ثم قم بالتأكيد. المفتاح الكامل
يتم عرض السر مرة واحدة — انسخه وخزنه بأمان.

**3. استخدم المفتاح**

مرر المفتاح في رأس `X-API-Key` مع كل طلب:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/consumer/protections \
  -H "X-API-Key: tlk_your_key_here"
```

للحصول على تفاصيل كاملة حول إدارة مفاتيح المستهلك، راجع [consumer portal guide](https://docs.truthlocks.com/ar/guides/consumer-portal.md#api-keys).

## رموز Bearer (JWT)

تُستخدم رموز JWT عندما تحتاج إلى إجراء مكالمات API نيابة عن مستخدم مصادق عليه، مثل من تطبيق ويب أو جوال.

### استخدام رموز الحامل

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

### هيكل الرمز المميز

```json theme={null}
{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "email": "user@example.com",
  "roles": ["admin"],
  "iat": 1705147200,
  "exp": 1705150800,
  "iss": "https://auth.truthlocks.com"
}
```

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

| نوع الرمز المميز | مدة الصلاحية | التحديث |
| - | - | - |
| رمز الوصول | ساعة واحدة | عبر رمز التحديث |
| رمز التحديث | 30 يومًا | عبر إعادة المصادقة |

## المصادقة متعددة العوامل للمصادق لحسابات Console

في Console، افتح **Settings → Security → Authenticator MFA** لربط Google Authenticator أو تطبيق مصادقة آخر يعتمد على الوقت.

1. تأكيد كلمة مرور Truthlocks المحلية الحالية الخاصة بك.
2. امسح رمز QR الخاص، أو أدخل مفتاح الإعداد في تطبيق المصادقة الخاص بك كحساب يعتمد على الوقت.
3. أدخل الرمز المكون من ستة أرقام من التطبيق لتمكين المصادقة متعددة العوامل (MFA).
4. احفظ رموز الاسترداد العشرة المعروضة بعد التأكيد. يتم عرضها مرة واحدة، ويعمل كل رمز مرة واحدة.

تتطلب عمليات تسجيل الدخول الجديدة العامل الثاني بعد كلمة المرور الخاصة بك أو مزود هوية عملك. تنتهي صلاحية خطوة التحقق بعد خمس دقائق. تؤدي الرموز غير الصحيحة المتكررة إلى قفل التحقق مؤقتًا للحساب. لا يمكن إعادة استخدام رمز تم قبوله بالفعل.

لاستبدال رموز الاسترداد أو تعطيل المصادقة متعددة العوامل (MFA)، قم بتأكيد كلمة المرور الخاصة بك ورمز مصادقة جديد أو رمز استرداد غير مستخدم. يؤدي استبدال رموز الاسترداد إلى إبطال المجموعة السابقة. يمكن لمستخدمي تسجيل الدخول الموحد (SSO) الذين لم يقموا بتعيين كلمة مرور Truthlocks محلية مطلقًا استخدام تدفق إعادة تعيين كلمة المرور لبريدهم الإلكتروني المسجل قبل التسجيل.

ينطبق تسجيل المصادقة متعددة العوامل (MFA) على حسابك الخاص. لا يسجل أعضاء آخرين أو يفرض متطلب MFA على مستوى مساحة العمل. لا يؤدي تمكين MFA إلى إلغاء الجلسات الحالية تلقائيًا. تظل مفاتيح API بيانات اعتماد نظام منفصلة.

## أفضل ممارسات الأمان

> [card] ✅ استخدام إدارة الأسرار
>
> قم بتخزين مفاتيح API في Google Secret Manager أو HashiCorp Vault أو ما شابه ذلك. لا تقم أبدًا
> مفاتيح مشفرة في كود التطبيق.

> [card] ✅ تدوير المفاتيح بانتظام
>
> أنشئ مفاتيح جديدة وقم بإلغاء المفاتيح القديمة بشكل دوري. استخدم أسماء وصفية مع
> التواريخ (مثل "Backend-2026-Q1").

> [card] ✅ تقييد النطاقات
>
> امنح الأذونات المطلوبة فقط. راجع ودقق نطاقات المفاتيح
> بانتظام.

> [card] ❌ لا تعرض أبدًا في الواجهة الأمامية
>
> يجب عدم تضمين مفاتيح API أبدًا في JavaScript من جانب العميل. استخدم رموز JWT
> لمصادقة الواجهة الأمامية.

> [card] ❌ لا تقم أبدًا بالالتزام بـ Git
>
> استخدم متغيرات البيئة أو إدارة الأسرار. أضف `.env*` إلى
> `.gitignore`.

## الخطوات التالية

> [card] [بوابة المستهلك](https://docs.truthlocks.com/guides/consumer-portal.md)
>
> إدارة مفاتيح API للمستهلك، والحماية، والإعدادات.

> [card] [البيئات](https://docs.truthlocks.com/environments.md)
>
> تكوين بيئة الاختبار مقابل الإنتاج وعناوين URL الأساسية.

> [card] [التحكم في الوصول المستند إلى الدور (RBAC) والأذونات](https://docs.truthlocks.com/security/rbac.md)
>
> فهم الأدوار والأذونات والتحكم في الوصول.

> [card] [سجلات التدقيق](https://docs.truthlocks.com/security/audit.md)
>
> تتبع جميع أنشطة API والأحداث الأمنية.


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