الاستيثاق Authentication

نشرح في هذا المقال طريقة تنفيذ الاستيثاق في الواجهة البرمجية لزيتون، وطريقة تسجيل دخول وخروج الوكلاء للواجهة مع أمثلة توضيحية.

تسجيل الدخول

تستخدم نقطة الوصول Login لتسجيل الدخول للواجهة البرمجية والتحقق من هوية الوكيل المتصل، ومنحه صلاحية الوصول للبيانات والوظائف المناسبة في مركز المساعدة.

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

الفرق بين رمز الوصول ومفتاح الواجهة البرمجية

رمز الوصول Access Token خاص بوكيل معين ويمثل جلسة اتصال محددة له، فهو يستخدم لتوثيق هوية وكيل معين خلال جلسة الاتصال، ويمنحه صلاحية الوصول لموارد معينة، أما المفتاح API Key فهو خاص بالتطبيق ويتيح لنا الاتصال بالواجهة البرمجية والوصول لوظائف وبيانات محددة حسب صلاحيات المفتاح.

كما أن رمز الوصول محدود بصلاحية زمنية محددة ولا يعود صالحًا للاستخدام بعدها، أما المفتاح فهو صالح دومًا ما لم نغيره أو نلغيه، ويمكن الحصول عليه من صفحة الحساب في مركز المساعدة كما شرحنا في مقال الاتصال بالواجهة البرمجية.

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

لتسجيل دخول وكيل له البريد الإلكتروني email@example.com إلى مركز مساعدة له النطاق example.com، سنكتب طلب POST على النحو التالي:

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

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

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

curl "https://example.com/api/agent/v1/contacts" \
  --header "Authorization: Bearer access_token"

تسجيل الخروج

لتسجيل خروج الوكيل من مركز مساعدة، نرسل طلب POST لنقطة الوصول Logout مع تمرير رمز الوصول الخاص بالوكيل ضمن ترويسة الطلب كما يلي:

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