الاستيثاق Authentication

محتويات الصفحة

تتوفر نقطتا اتصال لتسجيل الدخول والخروج لمستخدمي تطبيقك.

عند إرسال بريد المستخدم وكلمة المرور الخاصة به إلى نقطة الاتصال login/ ستعيد لك الواجهة معلومات عامة عن المستخدم مثل اسمه، ورقمه التعريفي id، وصورته الشخصية، وحالته فعّال أم غير فعّال وغيرها من المعلومات. ورمز وصول access_token خاص به يمكنه استخدامه للوصول إلى نقاط الاتصال الأخرى في الواجهة حسب صلاحياته، ونوع هذا الرمز token_type وهو في حالتنا Bearer وتاريخ انتهاء صلاحيته expires_at.

الفرق بين رمز الوصول access token ومفتاح API key

رمز الوصول access token خاص بمستخدم معين ويمثل جلسة اتصال محددة له بمعنى آخر يستخدم هذا الرمز لتوثيق هوية مستخدم معين في جلسة اتصال محددة، ويمنحه صلاحية الوصول إلى موارد معينة، أما مفتاح API فهو خاص بتطبيقك البرمجي يتيح له الاتصال بالواجهة البرمجية والوصول لوظائف وبيانات محددة بناءً على صلاحيات ذلك المفتاح.
رمز الوصول access token محدود بصلاحية زمنية محددة لا يعود صالحًا بعدها، أما مفتاح API فهو صالح دومًا ما لم تغيره أو تلغيه، ويمكنك الحصول عليه بالنقر على أيقونة حسابك الموجودة في الزاوية العلوية اليسرى في واجهة مركز المساعدة والدخول إلى تعديل الحساب.

ثم الضغط على زر إعادة توليد، بعد التأكد من تفعيل خيار توليد مفاتيح الواجهة البرمجية API key

طلب تسجيل دخول

سنرسل طلبPOST لتسجيل دخول باسم أحد مستخدمي مركز المساعدة إلى نقطة الاتصال login/ كما يلي

عنوان URL

support.example.com/api/agent/v1/login

جسم الطلب Body

يُكتب بصيغة JSON ويتضمن المعاملات التالية:

email	معامل إجباري، نوعه سلسلة نصية string، يستخدم لتمرير اسم البريد الإلكتروني للمستخدم email@exampel.com
password	معامل إجباري، نوعه سلسلة نصية string نمرر من خلاله كلمة المرور الخاصة بالمستخدم.

تسجيل الدخول باستخدام cURL

تكتب طلبات POST في cURL وفق الصيغة العامة التالية:

curl -X POST <url> --header 'your_header ' --data '{your_data}'

إذا استبدلنا <url> بعنوان نقطة الاتصال، والمصفوفة '{your_data}' ببيانات المستخدم يصبح الطلب بالشكل التالي:

curl -X POST 'https://support.example.com/api/agent/v1/login' --header 'Content-Type: application/json' --data '{"email": "email@exampel.com", "password": "your_password"}'

إذا كنت تعمل في بيئة ويندوز اكتب الطلب على هذا النحو:

curl -X POST "https://support.example.com/api/agent/v1/login" --header "Content-Type: application/json" --data "{\"email\": \"email@example.com\", \"password\": \"your_password\"}"

إذا كانت كافة بيانات الطلب صحيحة ستحصل على استجابة تشبه التالي:

{
    "data": {
        "id": "1440",
        "first_name": "your_first_name",
        "last_name": "your_last_name",
        "avatar": "https://avatars.hsoubcdn.com/default?s=128",
        "email": "email@example.com",
        "status": "active",
        "last_seen_at": "2024-08-17T08:50:20.970465Z",
        "notify_after": 6,
        "valid_locale": "ar",
        "locale": null,
        "block_login_until": null,
        "online_status": "offline",
        "change_password_required": false,
        "created_at": "2024-08-02T18:08:08+00:00",
        "notified_at": "2024-08-03T21:25:00+00:00",
        "updated_at": "2024-08-17T08:48:45+00:00"
    },
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type": "Bearer",
    "expires_at": "2025-02-17 10:54:54",
    "status": "success"
}

انتبه لصحة كتابة البريد الإلكتروني وكلمة المرور فأي خلل بهما يعني فشل الدخول وحصولك على الخطأ 401 Unauthorized.

لاستخدام رمز الوصول access token الذي حصلنا عليه من تسجيل الدخول السابق وعرض جميع جهات الاتصال نرسل طلب GET لنقطة الاتصال contacts/ كالتالي:

curl "https://support.example.com/api/agent/v1/contacts" --header "Authorization: Bearer your_access_token" -o contacts.json

لا نحتاج لكتابة أي راية flag قبل طلبات GET في cURL كما في طلب POST فهو يفهمها مباشرة. وقد استخدمنا الخيار o- لتصدير الخرج إلى ملف JSON لسهولة القراءة.

إذا امتلك المستخدم صاحب رمز الوصول access token صلاحية الوصول لجهات الاتصال فسنحصل في الاستجابة على ملف JSON يشبه التالي:

أما إذا كان لا يمتلك صلاحية الوصول إلى جهات الاتصال فسنحصل على الرمز 401 Unauthorized والاستجابة التالية:

{
    "status": "failed",
    "reason": "authentication_failed",
    "messages": [
        {
            "code": "authentication.failed",
            "message": "فشلت عملية الدخول، ليست لديك الصلاحيات لذلك"
        }
    ]
}

تسجيل الخروج

لتسجيل الخروج نرسل طلب POST إلى نقطة الاتصال logout/ دون أي معاملات إضافية فقط مع تمرير رمز الوصول access token الخاص بالمستخدم ضمن ترويسة الطلب كما يلي:

curl -X POST "https://support.example.com/api/agent/v1/logout" --header "Authorization: Bearer your_access_token"

في حال كان تسجيل الخروج ناجحًا ستحصل على الرمز 200 والاستجابة التالية:

{
    "status": "success"
}