المصادقة

Markdown

يرشدك هذا الدليل خلال المصادقة مع Human Dashboard وإنشاء x-unico-accesskey الذي ستستخدمه في جميع طلبات واجهة Human Token API.

يتكوّن التدفق من مرحلتين:

المصادقة — أكمل تسجيل الدخول واحصل على رمز وصول. تتوفر طريقتان للمصادقة:
- تسجيل الدخول البيومتري — التقاط الوجه عبر Unico SDK (متاح لكل من إنشاء الحساب وتسجيل الدخول)
- تسجيل الدخول برمز OTP عبر البريد الإلكتروني — رمز لمرة واحدة يُرسل إلى عنوان البريد الإلكتروني المسجّل (لتسجيل الدخول فقط)
إعداد مؤسستك — أنشئ ملف شركتك وأنشئ مفتاح وصول (عند إنشاء الحساب لأول مرة فقط)

طريقتان لإعداد بيانات الاعتماد

يمكن أيضًا تنفيذ كل ما في هذا الدليل عبر Human Dashboard على dashboard.unico.app — دون الحاجة إلى أي استدعاءات API.

الخيار	متى تُستخدم
Dashboard	الإعداد لأول مرة، وتدوير المفاتيح يدويًا، والإدارة العرضية
API	التزويد الآلي، وخطوط CI/CD، وإدارة المفاتيح برمجيًا

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

انتقل إلى dashboard.unico.app
أنشئ حسابًا أو سجّل الدخول — استخدم تسجيل الدخول البيومتري (التقاط الوجه) أو رمز OTP عبر البريد الإلكتروني
أنشئ مؤسستك — املأ اسم شركتك والبلد والنطاقات المسموح بها
أنشئ مفتاح وصول — انتقل إلى Access Keys وانقر على Create key؛ انسخه فورًا، إذ يُعرض مرة واحدة فقط
أدِر الفروع — أنشئ الفروع واضبط إعداداتها ضمن Branches؛ يُنشئ كل فرع مفتاح الوصول الخاص به

مفتاح الوصول الذي تحصل عليه من لوحة التحكم هو نفس x-unico-accesskey المستخدم في جميع طلبات API — الطريقتان قابلتان للتبادل بالكامل.

عناوين URL الأساسية

تُقدِّم Human Dashboard API كل نقاط النهاية في هذه الصفحة. أما طلبات واجهة Human Token API، مثل Create Process وGet Process، فتُرسَل إلى مضيف API المُدرَج في البيئات.

البيئة	API	عنوان URL الأساسي
الإنتاج	Human Dashboard API (تسجيل الدخول، والمؤسسة، ومفاتيح الوصول، والفروع)	`https://api.humantoken.unico.app`

طرق المصادقة

تتوفر طريقتان للمصادقة والحصول على authToken:

الطريقة	نقطة النهاية	متى تُستخدم
بيومترية	`POST /api/console/v1/auth/biometric/sessions`	إنشاء حساب (حساب جديد) أو تسجيل الدخول (مستخدم عائد)
OTP عبر البريد الإلكتروني	`POST /api/console/v1/auth/email/sessions`	لتسجيل الدخول فقط — يجب أن يكون الحساب موجودًا مسبقًا

نية تسجيل الدخول البيومتري

يجب أن يصرّح كل استدعاء لـ POST /api/console/v1/auth/biometric/sessions بقيمة intent:

`intent`	متى تُستخدم	الحقل `email`	الحقل `name`
`LOGIN_INTENT_SIGNUP`	التسجيل لأول مرة — إنشاء حساب جديد	مطلوب	مطلوب
`LOGIN_INTENT_SIGNIN`	مستخدم عائد — الحساب موجود بالفعل	غير مستخدم	غير مستخدم
(محذوف)	يُعامَل على أنه `LOGIN_INTENT_SIGNIN`	غير مستخدم	غير مستخدم

تتحكم النية في التحقق الذي يُجرى عند استطلاع الجلسة (الخطوة 2):

SIGNUP — يرفض تسجيل الدخول إذا كانت تلك الهوية البيومترية مسجّلة بالفعل (يمنع تكرار الحسابات).
SIGNIN — يرفض تسجيل الدخول إذا كانت تلك الهوية البيومترية غير مسجّلة (يجب أن يكون الحساب موجودًا لتسجيل الدخول).

المرحلة 1 — المصادقة

الخطوة 1: بدء جلسة تسجيل دخول بيومتري

SIGNUP (التسجيل لأول مرة)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "[email protected]",
    "name": "Jane Doe"
  }'

تفرّد البريد الإلكتروني

إذا كان هناك حساب مسجّل بالفعل بهذا البريد الإلكتروني، يُرجع الطلب 400 Bad Request.

الاستجابة:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "",
    "token": ""
  }
}

بالنسبة إلى SIGNUP، يكون الحقلان link وtoken فارغين في الاستجابة — إذ يُرسل رابط الالتقاط البيومتري إلى عنوان البريد الإلكتروني المُقدَّم.

SIGNIN (مستخدم عائد)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'

الاستجابة:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "https://humantoken.unico.io/...",
    "token": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

احفظ sessionId.

SIGNUP: يُرسل رابط الالتقاط البيومتري إلى البريد الإلكتروني المُقدَّم في الخطوة 1. اطلب من المستخدم التحقق من صندوق الوارد وإكمال الالتقاط.
SIGNIN: افتح link في متصفحك وأكمل الالتقاط البيومتري.

الخطوة 2: الاستطلاع حتى تُحسم الجلسة

curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345

استطلع كل 2–3 ثوانٍ حتى تصل status إلى حالة نهائية.

`status`	`outcome`	المعنى
`pending`	`pending`	لم يُكمل المستخدم الالتقاط بعد — واصل الاستطلاع
`processing`	`pending`	اكتمل الالتقاط، وجارٍ حساب النتائج — واصل الاستطلاع
`completed`	`matched`	نجح تسجيل الدخول — `authToken` موجود
`completed`	`no_match`	لم تتطابق البيانات البيومترية مع أي سجل
`completed`	`inconclusive`	نجح الالتقاط لكن تعذّر حسمه
`expired`	—	انتهت صلاحية الرابط — ابدأ من جديد من الخطوة 1
`canceled`	—	أُلغيت الجلسة — ابدأ من جديد من الخطوة 1

أخطاء إضافية خاصة بالنية عند استطلاع الجلسة:

HTTP	الشرط
`400`	SIGNUP — الهوية البيومترية مسجّلة بالفعل (حساب مكرر)
`400`	SIGNIN — الهوية البيومترية غير مسجّلة (الحساب غير موجود)

استجابة ناجحة:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

احفظ authToken — استخدمه كترويسة x-console-authorization في جميع طلبات Human Dashboard API اللاحقة.

المرحلة 1 (بديلة) — تسجيل الدخول برمز OTP عبر البريد الإلكتروني

استخدم هذا التدفق بدلًا من التدفق البيومتري إذا كان لدى المستخدم حساب بالفعل ويفضّل المصادقة عبر رمز لمرة واحدة يُرسل إلى بريده الإلكتروني المسجّل. لا يدعم رمز OTP عبر البريد الإلكتروني إنشاء الحساب — استخدم التدفق البيومتري للتسجيل لأول مرة.

الخطوة 1: إرسال رمز OTP

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

ملاحظة

يجب أن ينتمي البريد الإلكتروني إلى حساب موجود. إذا لم يُعثر على أي حساب، فستُرجع الخطوة 2 (التحقق من رمز OTP) الرمز 404 Not Found.

الاستجابة:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"
  }
}

احفظ sessionId. يُرسل رمز مكوّن من 6 أرقام إلى عنوان البريد الإلكتروني المُقدَّم.

الخطوة 2: التحقق من رمز OTP

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}

HTTP	الشرط
`200`	الرمز صالح — `authToken` موجود
`400`	الرمز خاطئ (`invalid otp code`)
`400`	رمز OTP مُستخدم بالفعل، أو بلغ الحد الأقصى للمحاولات، أو انتهت صلاحيته
`404`	البريد الإلكتروني غير مسجّل

استجابة ناجحة:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

احفظ authToken — استخدمه كترويسة x-console-authorization في جميع طلبات Human Dashboard API اللاحقة.

المرحلة 2 — إعداد مؤسستك

الخطوة 3: إنشاء مؤسستك

ملاحظة

يمكن إجراء هذا الاستدعاء مرة واحدة فقط. فهو يزوّد المستأجر الخاص بك وينشئ branchId.

يُقبل أي بلد. استخدم الرمز الثلاثي الأحرف وفق ISO 3166-1 alpha-3 (مثلاً BRA، USA، MEX، DEU، IND). الحقل taxId اختياري لجميع البلدان.

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "logo": "https://acme.com/logo.png",
    "allowedDomains": ["https://app.acme.com"]
  }'

الاستجابة:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

احفظ branchId — فهو يحدد فرعك الافتراضي ويُستخدم عند إدارة الفروع ومفاتيح الوصول.

الخطوة 4: إنشاء مفتاح وصول

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-key"
  }'

الاستجابة:

{
  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"
}

تحذير

يُرجَع accessKey مرة واحدة فقط ولا يمكن استرجاعه مرة أخرى. احفظه فورًا في مدير الأسرار لديك باسم HUMAN_TOKEN_ACCESS_KEY.

هذه القيمة هي ترويسة x-unico-accesskey المستخدمة في جميع طلبات واجهة Human Token API.

ما أصبح لديك الآن

القيمة	أين تُستخدم
`branchId`	تحديد فرعك الافتراضي؛ وإنشاء مفاتيح وصول خاصة بالفرع
`accessKey`	ترويسة `x-unico-accesskey` في جميع طلبات Human Token

إدارة مؤسستك

الحصول على المؤسسة

curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \
  -H "x-console-authorization: <authToken>"

الاستجابة:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

تحديث المؤسسة

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "taxId": "12345678000195",
    "logo": "https://acme.com/logo-updated.png",
    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]
  }'

إدارة مفاتيح الوصول

عرض المفاتيح (البيانات الوصفية فقط — لا يُرجَع السر أبدًا):

curl https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>"

تدوير مفتاح (يُبطَل المفتاح القديم فورًا):

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

إلغاء مفتاح (لا يمكن التراجع عنه):

curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

إدارة الفروع

تتيح لك الفروع تقسيم إعدادات مؤسستك (الاسم والشعار والنطاقات المسموح بها) حسب المنتج أو البيئة. لكل فرع مفاتيح الوصول الخاصة به، لذا يُستنتج سياق الفرع تلقائيًا من المفتاح المستخدم في الطلب — لا حاجة لتمرير branchId في CreateProcess.

إنشاء فرع

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "logo": "https://acme.com/mobile-logo.png",
    "allowedDomains": ["https://mobile.acme.com"]
  }'

الاستجابة:

{
  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
}

احفظ branchId — استخدمه عند إنشاء مفتاح وصول خاص بالفرع.

تحديث فرع

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",
    "name": "Mobile App v2",
    "logo": "https://acme.com/mobile-logo-v2.png",
    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]
  }'

إنشاء مفتاح وصول خاص بالفرع

لإنشاء مفتاح وصول مقيّد بفرع محدد، أضف branchId في نص الطلب:

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "mobile-app-key",
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
  }'

الاستجابة:

{
  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"
}

تحذير

يُرجَع accessKey مرة واحدة فقط. احفظه فورًا. سيستخدم أي طلب CreateProcess مُصادَق عليه بهذا المفتاح تلقائيًا إعدادات الفرع المرتبطة به.

طريقتان لإعداد بيانات الاعتماد​

استخدام لوحة التحكم​

عناوين URL الأساسية​

طرق المصادقة​

نية تسجيل الدخول البيومتري​

المرحلة 1 — المصادقة​

الخطوة 1: بدء جلسة تسجيل دخول بيومتري​

الخطوة 2: الاستطلاع حتى تُحسم الجلسة​

المرحلة 1 (بديلة) — تسجيل الدخول برمز OTP عبر البريد الإلكتروني​

الخطوة 1: إرسال رمز OTP​

الخطوة 2: التحقق من رمز OTP​

المرحلة 2 — إعداد مؤسستك​

الخطوة 3: إنشاء مؤسستك​

الخطوة 4: إنشاء مفتاح وصول​

ما أصبح لديك الآن​

إدارة مؤسستك​

الحصول على المؤسسة​

تحديث المؤسسة​

إدارة مفاتيح الوصول​

إدارة الفروع​

إنشاء فرع​

تحديث فرع​

إنشاء مفتاح وصول خاص بالفرع​

طريقتان لإعداد بيانات الاعتماد

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

عناوين URL الأساسية

طرق المصادقة

نية تسجيل الدخول البيومتري

المرحلة 1 — المصادقة

الخطوة 1: بدء جلسة تسجيل دخول بيومتري

الخطوة 2: الاستطلاع حتى تُحسم الجلسة

المرحلة 1 (بديلة) — تسجيل الدخول برمز OTP عبر البريد الإلكتروني

الخطوة 1: إرسال رمز OTP

الخطوة 2: التحقق من رمز OTP

المرحلة 2 — إعداد مؤسستك

الخطوة 3: إنشاء مؤسستك

الخطوة 4: إنشاء مفتاح وصول

ما أصبح لديك الآن

إدارة مؤسستك

الحصول على المؤسسة

تحديث المؤسسة

إدارة مفاتيح الوصول

إدارة الفروع

إنشاء فرع

تحديث فرع

إنشاء مفتاح وصول خاص بالفرع