الانتقال إلى المحتوى الرئيسي
POST
صك إثبات
يوقع حمولة باستخدام مفتاح توقيع متاح للمصدر ويسجل الإثبات الناتج. قد تمنع سياسة المصدر وحالة المفتاح والبيئة وحدود الاستخدام سك العملة.

اختر نوع السجل

لسجل منظم، اختر schema من القائمة المنسدلة لنوع السجل وأدخل كائن JSON في claims. اترك payload_b64url فارغًا. يقوم الخادم بتسلسل هذه الحقول في حمولة JSON الموقعة. هذا يحدد نوع السجل؛ ولا يثبت بشكل مستقل أن المطالبات صحيحة.

اختر حزمة تحقق

تنتمي حزم التحقق إلى مساحة عملك. استخدم المحدد أدناه بنفس البيئة ومفتاح API كما في Try it، ثم انسخ المعرف المحدد إلى pack_id. احذف هذا الحقل لسجل مستقل. يمكنك أيضًا استخدام List verification packs أو Mint in Console.

استخدام حمولة موجودة

إذا كان لديك البايتات الدقيقة للتوقيع بالفعل، فاحذف schema و claims. قم بترميز البايتات الأصلية كـ base64url غير مبطن في payload_b64url. بالنسبة لـ JSON، قم بتسلسل الكائن أولاً. تنتمي حقول التطبيق مثل subject و claims و schema داخل تلك البايتات المشفرة؛ استخدمها إما من خلال الإدخال المنظم أعلاه أو داخل البايتات المشفرة، ولا تستخدم كليهما أبدًا. لا تتحقق نقطة النهاية هذه بشكل مستقل من صحة المطالبات المقدمة أو تتحقق من صحة مخططات الاعتماد العشوائية. استخدم kid للمفتاح و alg المطابق. لا يؤدي تسجيل المفتاح العام وحده إلى توفير مفتاح توقيع خاص. انظر مفاتيح المُصدر.

انتهاء الصلاحية الاختياري

لـ schema و claims المنظمين، اضبط expires_at_unix على طابع زمني Unix مستقبلي بـ الثواني. يتضمن Truthlocks ذلك في جذر حمولة JSON الموقعة. مع payload_b64url، ضع هذا الحقل داخل حمولة JSON الدقيقة قبل ترميزها وحذف حقل الطلب المنفصل. بعد تلك اللحظة، يعيد التحقق EXPIRED. لا يمكن تمديد انتهاء الصلاحية أو إزالته من سجل موقع موجود؛ قم بإنشاء بديل. احذفه عندما لا ترغب في انتهاء صلاحية التصديق. التواريخ داخل المطالبات الفردية، مثل expiry_date لجواز السفر، هي مطالبات منفصلة ولا تحدد تلقائيًا انتهاء صلاحية التصديق. لا يتم تعيين تاريخ للسجلات الموجودة بأثر رجعي. احتفظ بالحمولة الدقيقة وتاريخ انتهاء الصلاحية عند إعادة المحاولة. تعيد المحاولة المتطابقة السجل الأصلي حتى بعد انتهاء صلاحيته.

إعادة المحاولة بأمان

Idempotency-Key مطلوب. قم بإنشاء قيمة واحدة لكل سك مقصود واحتفظ بها مع الطلب الأصلي لإعادة المحاولات. لا تعيد استخدامها لمحتوى مختلف.

سلامة المستندات

يتم تحديد تجزئة المستند المخزنة بهذا الترتيب:
  1. claims.document.sha256 داخل حمولة JSON.
  2. document_hash للطلب.
  3. SHA-256 لبايتات الحمولة المفككة.
تأخذ التجزئة المضمنة الأسبقية على الحقل المنفصل. قم بتضمين التجزئة في الحمولة الموقعة عندما تحتاج إلى ربط هذا الادعاء بالتوقيع. التجزئة المقدمة هي ادعاء حول ملف؛ لا يمكن للخادم تحديد محتويات الملف من التجزئة وحدها. مرر document_hash_hex إلى verification لمقارنة تجزئة ملف. احتفظ بالحمولة الأصلية للتحقق من سلامة الحمولة.

الاستجابة والتسليم

يعيد HTTP 201 attestation_id، issued_at_unix، signature، و log. موقع السجل هو log.leaf_index، وليس log_index على المستوى الأعلى. recipient_email يطلب إشعارًا غير متزامن. يؤكد HTTP 201 السك، وليس تسليم البريد الإلكتروني. احذفه عند توزيع السجل بنفسك. راجع دليل البدء السريع لطلب يستخدم حقول الإدخال والاستجابة الفعلية.

دليل حقل نوع السجل

هذه الحقول هي هياكل مطالبات مقترحة، وليست ضمانًا للتحقق من المطالبة أو التحقق من الهوية.

التفويضات

X-API-Key
string
header
مطلوب

مفتاح API للمصادقة من جهاز إلى جهاز

الترويسات

Idempotency-Key
string
مطلوب

احتفظ بنفس القيمة ونص الطلب عند إعادة محاولة سك واحد.

الجسم

application/json

اختر سجل منظم لتحديد نوع السجل وإدخال المطالبات، أو حمولة مشفرة لتوقيع البايتات الموجودة. لا تجمع أبدًا بين تنسيقي الإدخال.

alg
enum<string>
مطلوب

يجب أن يتطابق مع مفتاح توقيع جهة الإصدار المحدد.

الخيارات المتاحة:
Ed25519,
ES256,
ES384,
ES512,
RS256,
RS384,
RS512,
PS256,
PS384,
PS512
issuer_id
string<uuid>
مطلوب

معرف UUID للمصدر الذي ينشئ الشهادة

مثال:

"550e8400-e29b-41d4-a716-446655440000"

kid
string
مطلوب

معرف المفتاح لمفتاح التوقيع

مثال:

"es256-key-1"

schema
enum<string>
مطلوب

نوع السجل للإدخال المنظم. قدم المطالبات واحذف payload_b64url. هذا التصنيف لا يتحقق بشكل مستقل من صحة المطالبات.

الخيارات المتاحة:
verifiable-id,
passport,
drivers-license,
government-id,
self-sovereign-id,
employment-verification,
professional-role,
membership-card,
professional-certification,
license,
accreditation,
degree,
completion-cert,
course-credit,
transcript,
micro-credential,
training-completion,
medical-license,
dea-registration,
board-certification,
health-credential,
vaccination-record,
aml-kyc,
security-clearance,
sam-gov,
jurisdiction-approval,
attestation-of-will,
bank-verification,
credit-attestation,
income-verification,
skill-badge,
competency,
industry-cert,
product-authenticity,
chain-of-custody,
origin-verification,
custom,
attestation
مثال:

"verifiable-id"

claims
object
مطلوب

حقول سجل منظمة. مطلوبة مع المخطط؛ لا يمكن دمجها مع payload_b64url.

مثال:
attestation_id
string
content_type
string

نوع MIME للبايتات الأصلية، مثل application/json أو application/pdf أو image/png. يتطلب إدخال المخطط/المطالبات المنظمة application/json.

مثال:

"application/json"

document_hash
string

تجزئة مستند SHA-256 سداسية عشرية اختيارية. تأخذ claims.document.sha256 المضمنة الأسبقية؛ وإلا يتم استخدام هذا الحقل، ثم تجزئة الحمولة المفككة.

pack_id
string<uuid>

معرف UUID لحزمة التحقق من مساحة العمل الاختيارية. استخدم قائمة حزم التحقق بنفس مفتاح API لتحديد حزمة نشطة موجودة؛ احذفها لسجل مستقل.

expires_at_unix
integer<int64>

طابع زمني Unix مستقبلي اختياري بالثواني لإدخال المخطط/المطالبات المهيكلة. يتم تضمينه في حمولة JSON الموقعة. بالنسبة لإدخال payload_b64url، احذف حقل الطلب هذا وقم بتضمين expires_at_unix في جذر حمولة JSON الدقيقة بدلاً من ذلك. لا يمكن تغيير تاريخ انتهاء الصلاحية في مكانه.

النطاق المطلوب: 1 <= x <= 253402300799
recipient_email
string<email>

مستلم اختياري للإشعار غير المتزامن بعد السك. لا يؤكد رد السك الناجح التسليم.

الاستجابة

تم سك الإشهاد

attestation_id
string<uuid>
issuer_id
string<uuid>
version
string
status
string
expires_at_unix
integer<int64> | null

تاريخ انتهاء الصلاحية الموقع المسجل بثواني يونكس؛ يعني null عدم تسجيل تاريخ انتهاء صلاحية. لا يتم تعيين تاريخ انتهاء صلاحية جديد للسجلات القديمة.

issued_at_unix
integer<int64>
payload_hash
string
signature
object
log
object
governance
object | null