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

# رموز API والواجهة البرمجية العامة

> إنشاء رموز API شخصية وحصرها واختبارها وتدويرها وإلغاؤها بأمان، ثم استخدام مرجع الواجهة البرمجية العامة لتفاصيل نقاط التكامل.

رمز API هو بيانات اعتماد شخصية لاتصال خادم إلى خادم. يمكّن التكامل من المصادقة بصفة العضو الذي أنشأه؛ وليس كلمة مرور مشتركة للمؤسسة، ولا وسيلة لتجاوز التفويض المعتاد، ولا بديلاً عن تصميم تكامل له مالك مسؤول.

في مديرية خدمات المواطنين، امنح كل موصل اسماً لمالك فريقه وغرضاً معتمداً وتاريخ انتهاء أو مراجعة وخطة استبدال موثقة. فموصل تقارير الخدمات، مثلاً، يملكه فريق البنية التحتية ويُستخدم لعمل التقارير المعتمد فقط؛ ولا يصبح بيانات اعتماد قابلة للنسخ بين الفرق أو البيئات.

تشرح هذه الصفحة حوكمة الرمز ودورة حياته. راجع [مرجع الواجهة البرمجية العامة](/ar/reference/public-api) لعقد نقاط النهاية المدعومة وأشكال الطلبات وسلوك التفويض الخاص بكل نقطة نهاية.

## الهدف

إنشاء رمز يمكن تتبعه لتكامل واحد، وحفظ سره مرة واحدة في مخزن أسرار معتمد، والتحقق من اتصال محدود دون بيانات مواطنين فعلية، ثم إلغاء الرمز أو استبداله عندما يتغير مالكه أو غرضه أو مستوى مخاطره.

## الوصول والملكية والحدود الإدارية

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

| الإجراء              | من يستطيع تنفيذه                             | ما يجب التحقق منه                                                                    |
| -------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------ |
| إنشاء رمز            | العضو المسجل الذي ينشئ رمزه الشخصي           | أن العضو هو المالك المسؤول عن التكامل                                                |
| عرض **رموزي**        | مالك الرمز                                   | يظهر الاسم والحالة والانتهاء والتلميح وآخر استخدام؛ ولا يمكن استعادة السر من القائمة |
| عرض **رموز المؤسسة** | عضو يملك الفعل **api\_tokens.admin\_list**   | أن الغرض هو الجرد أو التدقيق وليس تصفح بيانات الاعتماد                               |
| إلغاء رمز شخصي نشط   | مالكه                                        | أن للتكامل بديلاً مختبراً أو خطة إيقاف معتمدة                                        |
| إلغاء رمز لعضو آخر   | عضو يملك الفعل **api\_tokens.admin\_revoke** | تأكيد المالك والرمز وسبب الحادث أو التغيير وأثره على التكامل                         |

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

## ما الذي تعرضه صفحة الرمز وتحفظه

| العنصر      | معناه                                                     | التعامل الآمن                                                        |
| ----------- | --------------------------------------------------------- | -------------------------------------------------------------------- |
| اسم الرمز   | تعريف مقروء للموصل                                        | ضمّن النظام والبيئة والغرض والمالك المسؤول                           |
| الحالة      | **نشط** أو **منتهٍ** أو **ملغى**                          | اعتبر الانتهاء أو الإلغاء نتيجة من دورة الحياة، لا خطأً يجب تجاوزه   |
| الانتهاء    | سنة واحدة افتراضياً، أو بلا انتهاء، أو تاريخ مستقبلي مخصص | فضّل تاريخ مراجعة معتمداً؛ واستخدم عدم الانتهاء فقط بقرار سياسة صريح |
| التلميح     | جزء نهائي قصير يساعد على تمييز الرمز                      | ليس سراً قابلاً للاستخدام ولا يثبت امتلاك الرمز                      |
| آخر استخدام | آخر استعمال رصده النظام، إن وجد                           | حقق في الاستعمال غير المتوقع قبل تغيير الصلاحيات أو الانتهاء         |
| المالك      | يظهر في جرد المؤسسة المصرح به                             | استخدمه لتحديد العضو المسؤول لا لمشاركة بيانات اعتماده               |

ينشئ النظام قيمة رمز ذات إصدار ويخزن تجزئة تشفيرية وتلميحاً قصيراً. يظهر السر الكامل فور الإنشاء فقط. إغلاق رسالة العرض لا يفتح طريق استرداد؛ أنشئ بديلاً ثم ألغ الرمز المفقود.

## قبل إنشاء رمز

1. عرّف غرضاً واحداً للتكامل وسمِّ مالكه التشغيلي. مثال جيد: **موصل تقارير خدمات المواطنين — فريق البنية التحتية — الإنتاج**. تجنب أسماء مثل **تكامل** أو لقب شخص.
2. تحقق من البيئة المستهدفة وعمليات الواجهة العامة المعتمدة وتصنيف البيانات والنظام المستلم. لا يستخدم الرمز لنقل بيانات مواطنين إلى نظام غير معتمد.
3. تحقق أن مالك الرمز يملك فقط الأدوار والنطاقات الأساسية التي يحتاجها التكامل. تجمع نافذة الإنشاء اسماً وانتهاءً ولا تنشئ نموذج نطاقات منفصلاً وواسعاً للرمز.
4. اختر تاريخ انتهاء ومالكاً للتجديد. المدة الافتراضية سنة واحدة؛ ويجب أن يكون التاريخ المخصص في المستقبل. يحتاج الرمز بلا انتهاء إلى استثناء صريح ومراجعة دورية.
5. جهز مدخل مخزن الأسرار المعتمد ومجموعة الوصول إليه قبل الضغط على **إنشاء رمز**. لا تخطط لنسخ السر في تذكرة أو محادثة أو بريد أو جدول أو مستودع مصدر أو قالب أو لقطة شاشة.
6. خطط لاختبار صغير غير إنتاجي وخطة رجوع: اعرف أي رمز ستلغيه إذا أرسل الاختبار طلباً غير متوقع.

## إنشاء الرمز وحفظه

افتح **الإدارة ← رموز API والواجهة البرمجية العامة**، وابق في تبويب **رموزي**، ثم اختر **إنشاء رمز**.

1. أدخل الاسم الدقيق واختر **سنة واحدة** أو **بلا انتهاء** أو **تاريخ مخصص**. للاختبار المؤقت، استخدم تاريخاً مخصصاً قصيراً عندما تسمح السياسة.
2. أنشئ الرمز. راجع السر المولد في رسالة العرض لمرة واحدة فقط بينما لا يرى الشاشة أي شخص آخر.
3. انسخه مباشرة إلى سجل مخزن الأسرار المُعد. ضع بجانب السر المالك والغرض والبيئة ووقت الإنشاء والانتهاء وتاريخ التدوير أو المراجعة، لكن لا تضع السر نفسه في توثيق عادي.
4. أغلق الرسالة بعد التأكد من قبول مخزن الأسرار للقيمة. ستعرض القائمة تلميحاً فقط ولن تعرض القيمة الكاملة.
5. شغّل أصغر اختبار اتصال معتمد باستخدام سجل اصطناعي أو عملية قراءة/غير مغيرة موثقة في مرجع الواجهة العامة.
6. حدّث **رموزي** وتأكد أن الرمز المتوقع ما زال نشطاً. عند وصول طلب إلى الخدمة، تحقق أن قيمة آخر استخدام منطقية بالنسبة للاختبار المضبوط.

استخدم عنصراً نائباً في أدلة التشغيل الداخلية، ولا تستخدم قيمة حية:

```http theme={null}
Authorization: Bearer KOS_TOKEN_FROM_APPROVED_SECRET_MANAGER
```

استبدل العنصر النائب فقط في بيئة تشغيل التكامل أو الاختبار الآمنة. لا تلصق رمزاً حقيقياً في شريط عنوان المتصفح أو تعبير أو حقل قالب مستند أو لقطة شاشة.

## مثال مضبوط للمديرية

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

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

## الجرد والتدوير والإلغاء

راجع جرد الرموز وفق دورة الحوكمة المعتمدة وفور انتقال المالك أو الاشتباه في تسرب أو استخدام غير مفسر أو مغادرة موظف أو إيقاف موصل.

1. استخدم **رموزي** للجرد الشخصي. ويمكن للمسؤول المصرح له اختيار **رموز المؤسسة** فقط عند امتلاكه **api\_tokens.admin\_list**.
2. طابق الاسم والمالك والحالة والانتهاء وآخر استخدام مع سجل التكاملات. علّم الأسماء المبهمة والرموز بلا مالك والإعدادات غير المخططة بلا انتهاء والقيم المنتهية والنشاط غير المتوقع.
3. دوّر الرمز بإنشاء رمز جديد مسمى وحفظه بأمان وتحديث التكامل وإثبات طلب مضبوط صغير بالبيانات الجديدة.
4. ألغ الرمز القديم فقط بعد التأكد من عمل البديل. الإلغاء يوقف الرمز فوراً ولا يمكن التراجع عنه.
5. عند الاشتباه بتسرب، ألغ الرمز أولاً، واحفظ أدلة التغيير أو الحادث ذات الصلة، وحدد موضع ظهور القيمة، ولا تنشئ بديلاً قبل ضبط مسار التسرب.
6. أزل التكاملات المتقاعدة من الجداول ومخازن الأسرار وفق السياسة. لا ينبغي أن يبقى الرمز الملغى اعتماداً تشغيلياً غير مفسر.

لا تعد التدوير بتغيير اسم رمز قائم أو تمديد تاريخ انتهائه دون مراجعة أو مشاركة رمز مع مالك بديل. الرموز مرتبطة بالعضو الذي أنشأها ويجب استبدالها تحت اسم المالك المسؤول الجديد.

## تحقق آمن

| الاختبار            | النتيجة المتوقعة                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| حفظ السر لمرة واحدة | ينسخ السر إلى مخزن الأسرار المعتمد مرة واحدة ولا يظهر ثانية في قائمة الرموز                                         |
| اتصال محدود         | ينجح طلب موثق وآمن فقط لغرض التكامل المعتمد                                                                         |
| مراجعة الملكية      | يحدد الاسم والجرد المصرح بهما العضو المسؤول والبيئة                                                                 |
| حد الصلاحيات        | لا يفتح عضو بلا **api\_tokens.admin\_list** جرد المؤسسة، ولا يلغي عضو بلا **api\_tokens.admin\_revoke** رمز عضو آخر |
| الانتهاء            | يظهر الرمز بعد مرور انتهائه كمنتهٍ ويستبدل عبر دورة الحياة المعتمدة                                                 |
| الإلغاء             | يتوقف الرمز الملغى فوراً، ويستمر البديل المختبر إن كان مهيأً                                                        |

## استكشاف الأخطاء وإصلاحها

| العرض                               | افحص أولاً                                                            | الاستجابة الآمنة                                                          |
| ----------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| فُقد الرمز الكامل بعد إغلاق الرسالة | سجل مخزن الأسرار وهل تم إعداد التكامل                                 | لا تطلب استعادته من الدعم؛ أنشئ رمزاً جديداً وحدّث التكامل ثم ألغ المفقود |
| لا يظهر تبويب رموز المؤسسة          | الفعل المعيّن **api\_tokens.admin\_list** والمؤسسة الحالية            | اطلب الدور الضيق المراجع ولا تستخدم جلسة مسؤول آخر                        |
| لا يتاح إلغاء رمز لمالك آخر         | الفعل **api\_tokens.admin\_revoke** وحالة الرمز والمؤسسة الحالية      | ينجز مسؤول مخول الإلغاء الذي تمت مراجعته                                  |
| الرمز منتهٍ                         | تاريخ الانتهاء ومالك التكامل وقرار التجديد                            | أنشئ بديلاً بتاريخ مستقبلي معتمد وحدّث الموصل                             |
| آخر استخدام غير متوقع               | الاسم أو التلميح والمالك والنافذة الزمنية وسجلات التكامل وسجل التغيير | عالجه كتحقيق أمني وألغ الرمز إذا كان التسرب محتملاً                       |
| يفشل طلب الواجهة العامة             | نقطة النهاية والطريقة الموثقتان وحالة الرمز والبيئة والتفويض الأساسي  | اختبر طلباً أصغر معتمداً واستخدم المرجع؛ لا توسع الوصول بلا دليل          |

## أدلة ذات صلة

* استخدم إرشادات التكامل الخاصة بنقطة النهاية في [مرجع الواجهة البرمجية العامة](/ar/reference/public-api).
* هيئ وصول الجرد والإلغاء بأقل صلاحية في [الأدوار والنطاقات](/ar/admin/roles-and-scopes).
* اضبط الملفات التي تنتجها التكاملات في [مهام التصدير](/ar/admin/export-jobs).
* راجع عناصر الإعدادات غير المتاحة في [الصلاحيات والإتاحة](/ar/reference/permissions-and-availability).

![إعدادات دورة حياة رمز API في KayanOS لمديرية خدمات المواطنين دون إظهار بيانات اعتماد.](https://kayanos.app/docs-images/ar/admin/api-tokens-and-public-api.png)