مرجع API · تسجيل المفتاح
إثبات حيازة المفتاح
POST
/v1/enrollments/{invitationId}/proofيرسل إثبات الحيازة. بعد قبوله ينتظر المفتاح أن يسجّل موظفو أنيس بصمته ويؤكّدوه.
الصلاحيةلا شيء
المصادقةرمز التسجيل
حدود الموظفين التي يُحتسب ضمنهالا شيء
حزمة SDK لـ .NET
enrollment.ProveAsync(submitted, key)- الإثبات الذي لا يُتحقق منه، أو الذي يأتي بعد نحو 30 دقيقة من إرسال المفتاح، لا يُرفض: الرد يقول
proofState: "failed". تحقّق من"accepted". - بعد خمسة إثباتات فاشلة تُرفض الإثباتات التالية بـ
rate_limitedحتى يعيد موظفو أنيس بدء التسجيل.
المعاملات
| الاسم | الموضع | النوع | ملاحظات |
|---|---|---|---|
invitationIdإلزامي | path | UUID | معرّف UUID بأحرف صغيرة مع الشرطات. |
الاستدعاء
مُصرَّح به عبر Authorization: Enrollment <token>؛ غير موقَّع.
الترويسات: Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.
المحتوى: EnrollmentProofRequest، بصيغة JSON.
| الحقل | النوع | ملاحظات |
|---|---|---|
keyIdإلزامي | UUID | معرّف المفتاح من خطوة إرسال المفتاح. |
challengeGenerationإلزامي | integer | رقم التحدّي الذي تجيب عنه. |
signatureإلزامي | string | توقيع ECDSA P-256/SHA-256 على رسالة الإثبات، 64 بايت (ليس DER)، بترميز base64url دون حشو. |
الردود
| الحالة | المعنى | المحتوى |
|---|---|---|
| 200 | نجاح. | EnrollmentStatus |
| 401 | مرفوض: لم تتم المصادقة. | مشكلة |
| 404 | مرفوض: غير موجود، أو ليس لك. | مشكلة |
| 409 | مرفوض: يتعارض مع الحالة الحالية. | مشكلة |
| 422 | مرفوض: الاستدعاء يخالف قاعدة. | مشكلة |
| 429 | مرفوض: بلغتَ حدًا. | مشكلة |
| 503 | لا قرار: خدمة مطلوبة غير متاحة. | مشكلة |
كل ردّ موقَّع من أنيس؛ وتتحقق منه حزم SDK قبل أن يصلك.
حالات الرفض
كل رفض مشكلةٌ موقَّعة. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.
| الخطأ | الرمز | الحالة |
|---|---|---|
| الدعوة غير صالحة | invitation_invalid | 401 |
| غير موجود | resource_not_found | 404 |
| فشل التحقق | validation_failed | 422 |
| استُبدل التحدّي | challenge_expired | 409 |
| تجاوزت حدّ الاستدعاءات | rate_limited | 429 |
| الخدمة غير متاحة | dependency_unavailable | 503 |
| انتهت مهلة الاستدعاء | request_timeout | 504 |
| خطأ داخلي | internal_error | 500 |
الأنواع
EnrollmentProofRequest
| الحقل | النوع | ملاحظات |
|---|---|---|
keyIdإلزامي | UUID | معرّف المفتاح من خطوة إرسال المفتاح. |
challengeGenerationإلزامي | integer | رقم التحدّي الذي تجيب عنه. |
signatureإلزامي | string | توقيع ECDSA P-256/SHA-256 على رسالة الإثبات، 64 بايت (ليس DER)، بترميز base64url دون حشو. |
EnrollmentStatus
| الحقل | النوع | ملاحظات |
|---|---|---|
keyId | UUID | معرّف مفتاحك. |
challengeGeneration | integer | رقم التحدّي الحالي. |
proofState | string | pending أو accepted أو failed — إثبات لم يُتحقق منه أو جاء متأخرًا. بعد خمسة إثباتات فاشلة، اطلب من موظفي أنيس إعادة بدء التسجيل. |
approvalState | string | pending ما دام موظفو أنيس لم يؤكّدوا المفتاح، و approved بعد أن يصبح فعّالًا، و notApplicable في غير ذلك. |
state | string | pendingProof أو pendingApproval أو active — المفتاح يوقّع الاستدعاءات — أو unavailable (أُلغي، أو انتهت صلاحيته، أو استُبدل). |
expiresAt | string (date-time) | وقت انتهاء الخطوة الحالية. |