المصادقة

Bearer فقط لا غير

المصادقة header واحد. يقرأ الخادم Authorization، ويطابق الصيغة دون حساسية لحالة الأحرف، ويأخذ بقية القيمة بيانات اعتماد.

Authorization: Bearer wa_live_<secret>

نوعان من بيانات الاعتماد، header واحد

الـ header نفسه يحمل إما API key لمساحة عمل، وإما access token لمستخدم. والاختيار بينهما يتبع: أيتصرف هنا جهاز أم إنسان.

يميّز الخادم بينهما ببادئة بيانات الاعتماد، فلا تحتاج أن تعلن أيهما ترسل. وبعض النقاط تقبل نوعا واحدا فقط: إنشاء API key ومسارات ربط QR تتطلب access token، لأن بيانات الاعتماد الآلية لا شخص خلفها ولا متصفح.

مفاتيح test وlive

يُنشأ المفتاح في وضع واحد ويبقى فيه. الوضع جزء من بيانات الاعتماد، ظاهر في بادئتها، ويغيّر ما يُسمح للمفتاح بفعله.

الـ header المسمى X-Workspace-Id

كل endpoint مرتبط بمساحة عمل يحتاج أن يعرف في أي مساحة يتصرف. ومصدر ذلك يتبع نوع بيانات الاعتماد.

• مع API key: مساحة العمل تأتي من المفتاح، والـ header اختياري.
• مع access token: الـ header مطلوب، لأن الشخص قد ينتمي إلى عدة مساحات. وإغفاله يعطي 400 برمز WORKSPACE_CONTEXT_REQUIRED.
• إرسال header يخالف مساحة عمل الـ API key نفسه يعطي 403، لا تجاوزا صامتا.

# An API key already names its workspace, so the header is optional...
curl https://whats.azzamkh.sa/api/v1/channels \
  -H "Authorization: Bearer $WA_API_KEY"

# ...but a USER access token belongs to a person, who may be in several.
curl https://whats.azzamkh.sa/api/v1/channels \
  -H "Authorization: Bearer <access token>" \
  -H "X-Workspace-Id: ws_..."

# Omitting it with a user token:
# 400 { "error": { "code": "WORKSPACE_CONTEXT_REQUIRED", ... } }

الصلاحيات

يحمل الـ API key مجموعة صلاحيات ثابتة تُختار عند الإنشاء. والطلب خارجها يعطي 403 مع الصلاحيات المطلوبة في details.

إنشاء مفتاح

تُنشأ المفاتيح بواسطة مستخدم مسجّل دخوله، لا بواسطة مفتاح آخر: فالمفتاح المخترق لا يستطيع أن يصكّ لنفسه مفتاحا أوسع.

# A key can only be minted by a signed-in user, never by another key.
curl -X POST https://whats.azzamkh.sa/api/v1/api-keys \
  -H "Authorization: Bearer <access token>" \
  -H "X-Workspace-Id: ws_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order service (test)",
    "mode": "test",
    "scopes": ["messages.send", "messages.read"]
  }'

# 201 Created — "secret" appears in THIS response and nowhere else.
# {
#   "id": "key_...",
#   "name": "Order service (test)",
#   "mode": "test",
#   "prefix": "wa_test",
#   "last4": "9f3a",
#   "scopes": ["messages.send", "messages.read"],
#   "expires_at": null,
#   "secret": "wa_test_..."
# }

التدوير والإلغاء

لا يوجد endpoint للتدوير. التدوير هو إنشاء ثم إلغاء، وهو الشكل الأسلم أصلا: يبقى المفتاح القديم عاملا حتى يُنشر الجديد.

curl -X DELETE https://whats.azzamkh.sa/api/v1/api-keys/key_... \
  -H "Authorization: Bearer <access token>" \
  -H "X-Workspace-Id: ws_..."

# 200 OK — repeating this returns the ORIGINAL revoked_at, not an error.
# { "id": "key_...", "revoked_at": "2026-08-13T10:00:00.000Z" }

بالترتيب:

• أنشئ مفتاحا جديدا بالصلاحيات والوضع نفسيهما.
• انشره، وتأكد أن الحركة تجري عليه.
• ألغِ المفتاح القديم. يسري الإلغاء فورا، وتكراره آمن: يعيد وقت الإلغاء الأصلي لا خطأ.

إخفاقات المصادقة

كل إخفاق يتبع الغلاف القياسي الموصوف في الأخطاء والحدود.

التعامل مع المفاتيح

• اقرأ المفاتيح من بيئة التشغيل. لا تودع مفتاحا في مستودع، ولا تضعه في كود يعمل في المتصفح.
• هذه الـ API سطح بين الخوادم. والمفتاح في المتصفح مفتاح نشرته للعالم.
• اطلب الصلاحيات التي تستعملها فحسب. تكامل يرسل فقط لا يحتاج contacts.manage.
• ابنِ على مفتاح test. والانتقال إلى live ينبغي أن يكون تغيير إعداد لا تغيير كود.