مرجع API · تسجيل المفتاح
إرسال مفتاح عام
POST
/v1/enrollments/{invitationId}/keysيرسل النصف العام من مفتاح P-256 جديد، ويتلقى التحدّي لإثبات أنك تملك النصف الخاص.
الصلاحيةلا شيء
المصادقةرمز التسجيل
ردّ أنيسموقَّع
حدود الموظفين التي يُحتسب ضمنهالا شيء
حزمة SDK لـ .NET
enrollment.SubmitKeyAsync(request)- احفظ المفتاح الخاص قبل هذا الاستدعاء: الدعوة الواحدة تأخذ مفتاحًا واحدًا بالضبط.
- يحمل الرد
safetyCode. سيتصل موظفو أنيس بجهة الاتصال الفنية لديك ويطلبون منها قراءته قبل أن يصبح مفتاحك فعّالًا.
المعاملات
| الاسم | الموضع | النوع | ملاحظات |
|---|---|---|---|
invitationIdإلزامي | path | UUID | معرّف UUID بأحرف صغيرة مع الشرطات. |
الاستدعاء
مُصرَّح به عبر Authorization: Enrollment <token>؛ غير موقَّع.
الترويسات: Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.
المحتوى: EnrollmentKeyRequest، بصيغة JSON.
| الحقل | النوع | ملاحظات |
|---|---|---|
publicJwkإلزامي | PublicJwk | النصف العام فقط من مفتاح P-256 جديد. العنصر الخاص يُرفض. |
notBeforeإلزامي | string (date-time) | يُستخدم طول النافذة فقط (حتى expiresAt)، ويبدأ حين يفعّل موظفو أنيس المفتاح. وتعتمد أنيس الأقصر بين مدة الصلاحية التي تطلبها والمدة التي حدّدها موظفو أنيس (ولا تزيد أبدًا على سنتين). |
expiresAtإلزامي | string (date-time) | نهاية مدة الصلاحية التي تطلبها. انظر notBefore. |
الردود
| الحالة | المعنى | المحتوى |
|---|---|---|
| 200 | نجاح. | EnrollmentKeyResult |
| 401 | مرفوض: لم تتم المصادقة. | مشكلة |
| 404 | مرفوض: غير موجود، أو ليس لك. | مشكلة |
| 409 | مرفوض: يتعارض مع الحالة الحالية. | مشكلة |
| 422 | مرفوض: الاستدعاء يخالف قاعدة. | مشكلة |
| 429 | مرفوض: بلغتَ حدًا. | مشكلة |
| 503 | لا قرار: خدمة مطلوبة غير متاحة. | مشكلة |
كل ردّ على هذا الاستدعاء موقَّع من أنيس — النجاح وكل رفض. اشترط وجود التوقيع وتحقّق منه قبل أن تتصرف بناءً على الردّ؛ والردّ بلا توقيع فشل، لا يُعدّ ردًّا (كيف).
حالات الرفض
كل رفض لهذا الاستدعاء مشكلةٌ موقَّعة. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.
| الخطأ | الرمز | الحالة |
|---|---|---|
| الدعوة غير صالحة | invitation_invalid | 401 |
| غير موجود | resource_not_found | 404 |
| فشل التحقق | validation_failed | 422 |
| المفتاح العام غير صالح | key_proof_invalid | 422 |
| الدعوة مستخدمة من قبل | key_duplicate | 409 |
| تجاوزت حدّ الاستدعاءات | rate_limited | 429 |
| الخدمة غير متاحة | dependency_unavailable | 503 |
| انتهت مهلة الاستدعاء | request_timeout | 504 |
| خطأ داخلي | internal_error | 500 |
الأنواع
EnrollmentKeyRequest
| الحقل | النوع | ملاحظات |
|---|---|---|
publicJwkإلزامي | PublicJwk | النصف العام فقط من مفتاح P-256 جديد. العنصر الخاص يُرفض. |
notBeforeإلزامي | string (date-time) | يُستخدم طول النافذة فقط (حتى expiresAt)، ويبدأ حين يفعّل موظفو أنيس المفتاح. وتعتمد أنيس الأقصر بين مدة الصلاحية التي تطلبها والمدة التي حدّدها موظفو أنيس (ولا تزيد أبدًا على سنتين). |
expiresAtإلزامي | string (date-time) | نهاية مدة الصلاحية التي تطلبها. انظر notBefore. |
PublicJwk
| الحقل | النوع | ملاحظات |
|---|---|---|
ktyإلزامي | string | دائمًا EC. القيم: EC |
crvإلزامي | string | دائمًا P-256. القيم: P-256 |
xإلزامي | string | الإحداثي x للمفتاح: 32 بايت بالضبط، بترميز base64url دون حشو. |
yإلزامي | string | الإحداثي y للمفتاح: 32 بايت بالضبط، بترميز base64url دون حشو. |
kid | string | في مفاتيح التوقيع لدى أنيس: المفتاح الذي يذكره توقيع الرد. تعامل معه كاسم مبهم. لا يُرسل حين ترسل مفتاحك أنت. |
use | string | الاستخدام المقصود، حين يُنشر. |
alg | string | الخوارزمية، حين تُنشر. |
EnrollmentKeyResult
| الحقل | النوع | ملاحظات |
|---|---|---|
keyIdموجود دائمًا | UUID | معرّف مفتاحك: وهو keyid الذي سيحمله كل توقيع بعد أن يصبح المفتاح فعّالًا. |
thumbprintموجود دائمًا | string | بصمة المفتاح (RFC 7638). وهي جزء من رسالة الإثبات التي توقّعها. |
safetyCodeموجود دائمًا | string | رمز الأمان المكوَّن من 16 خانة والمشتق من بصمة مفتاحك، ويُكتب XXXX-XXXX-XXXX-XXXX. سيتصل موظفو أنيس بجهة الاتصال الفنية لديك ويطلبون منها قراءته قبل أن يصبح مفتاحك فعّالًا. |
challengeموجود دائمًا | string | التحدّي الذي يجيب عنه إثباتك. لا يُرجَع إلا هنا: احتفظ به حتى يُقبل الإثبات. |
challengeGeneration | integer | رقم هذا التحدّي؛ وإعادة بدء التسجيل تصدر التحدّي التالي. |