مرجع API · مفاتيح التوقيع لدى أنيس
مفاتيح التوقيع العامة لدى أنيس
GET
/.well-known/partner-signing-keys.jsonكل مفتاح عام قد يوقّع ردود أنيس — ومنها المفتاح التالي قبل التدوير والسابق بعده. المسار الوحيد الذي لا يحتاج توقيعًا. تحتفظ به برامج العملاء لمدة لا تتجاوز 5 دقائق وتجلبه مجددًا حين يذكر ردٌّ مفتاحًا لم تره — مرة واحدة على الأكثر كل 30 ثانية.
الصلاحيةلا شيء
المصادقةعام
ردّ أنيسغير موقَّع
حدود الموظفين التي يُحتسب ضمنهالا شيء
حزمة SDK لـ .NET
Fetched and cached by the SDK- يُجيب بالحالة HTTP
503والرمزdependency_unavailableحين يتعذّر قراءة قائمة المفاتيح أو لم تُحدِّثها أنيس منذ 9 دقائق. احتفظ بنسختك المؤقتة حتى انتهاء صلاحيتها الأصلية (5 دقائق على الأكثر من وقت جلبها)، وأعِد المحاولة مع زيادة الانتظار تدريجيًا. وتستمر الاستدعاءات التي لا توقَّع ردودها في العمل.
الاستدعاء
بلا مصادقة.
المحتوى: لا يوجد.
الردود
| الحالة | المعنى | المحتوى |
|---|---|---|
| 200 | نجاح. | SigningKeySet |
| 503 | لا قرار: خدمة مطلوبة غير متاحة. | مشكلة |
هذا الردّ غير موقَّع: هو المستند الذي تتحقق به من بقية ردود أنيس. اجلبه عبر TLS فقط.
حالات الرفض
رفض هذا الاستدعاء مشكلةٌ بلا توقيع. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.
| الخطأ | الرمز | الحالة |
|---|---|---|
| الخدمة غير متاحة | dependency_unavailable | 503 |
الأنواع
SigningKeySet
| الحقل | النوع | ملاحظات |
|---|---|---|
keysموجود دائمًا | list of PublishedSigningKey | مفاتيح التوقيع العامة المنشورة بحالات active وnext وretired. يبقى المفتاح المُنهى مدرجًا 90 يومًا بعد retiredAt؛ وتُستبعد المفاتيح المخترقة. |
revokedموجود دائمًا | list of RevokedSigningKey | المفاتيح المخترقة، وتُدرج 90 يومًا بعد compromisedAt. تعلن أنيس الاختراق خلال 24 ساعة بالبريد الإلكتروني وهنا. |
PublishedSigningKey
| الحقل | النوع | ملاحظات |
|---|---|---|
ktyموجود دائمًا | string | دائمًا EC. القيم: EC |
crvموجود دائمًا | string | دائمًا P-256. القيم: P-256 |
xموجود دائمًا | string | 32 بايت بالضبط، بترميز base64url دون حشو. |
yموجود دائمًا | string | 32 بايت بالضبط، بترميز base64url دون حشو. |
kidموجود دائمًا | string | اسم مفتاح مبهم تستخدمه keyid في الردّ. |
useموجود دائمًا | string | دائمًا sig. |
algموجود دائمًا | string | دائمًا ES256. |
statusموجود دائمًا | string | active أو next أو retired. استخدمها للتحقق من وقت created للتوقيع. القيم: active, next, retired |
notBeforeموجود دائمًا | string (date-time) | وقت بدء بصيغة RFC3339؛ ارفض أي مفتاح — active أو next أو retired — حين تكون created أسبق منه. |
retiredAt | string (date-time) | وقت توقف التوقيع الاختياري بصيغة RFC3339؛ ارفض المفتاح المُنهى حين تكون created بعده. |
purpose | string | اختياري في المخطط للتوافق، لكن أنيس ترسله دائمًا. تحدّد answer مفاتيح ردود API، وتحدّد webhook مفاتيح الإشعارات. اشترط الغرض المطابق للرسالة. القيم: answer, webhook |
RevokedSigningKey
| الحقل | النوع | ملاحظات |
|---|---|---|
kidموجود دائمًا | string | معرّف المفتاح المخترق: ارفض ردوده بالسبب key_compromised. |
compromisedAtموجود دائمًا | string (date-time) | وقت الاختراق بصيغة RFC3339. الردود الموقَّعة بعده باطلة. |