المصادقة

مفاتيح API

تستخدم واجهة eWasl مفاتيح API لمصادقة الطلبات. كل مفتاح محكوم بصلاحيات محدّدة ويمكن إلغاؤه باستقلالية.

تتبع المفاتيح الصيغة ewasl_ متبوعةً بسلسلة عشوائية. وتُعرض مرة واحدة فقط عند الإنشاء — فاحفظها بأمان.

إنشاء مفتاح API

1. سجّل الدخول إلى حساب eWasl.
2. انتقل إلى Settings ← API Keys.
3. اضغط Create New Key.
4. أعطِ المفتاح اسماً وصفياً (مثل "Production App" أو "CI Pipeline" أو "MCP Integration").
5. اختر الصلاحيات التي يحتاجها مفتاحك (posts:read، posts:create).
6. انسخ المفتاح المُولّد فوراً — لن يُعرض مرة أخرى.

يمكنك أيضاً إنشاء المفاتيح برمجياً عبر نقطة إنشاء مفتاح.

استخدام مفتاح API

ضمّن المفتاح في ترويسة Authorization لكل طلب باستخدام مخطط Bearer:

Authorization: Bearer ewasl_YOUR_API_KEY

مثال: عرض المنشورات

curl https://app.ewasl.com/api/v1/posts \
  -H "Authorization: Bearer ewasl_abc123def456..."

مثال: إنشاء منشور

curl -X POST https://app.ewasl.com/api/v1/posts \
  -H "Authorization: Bearer ewasl_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from the eWasl API!",
    "accountIds": ["your-account-uuid"],
    "publishNow": true
  }'

اختيار مساحة العمل

تستخدم نقاط المنشورات افتراضياً مساحة العمل الشخصية لمالك بيانات اعتماد API. لتنفيذ الطلب داخل مساحة عمل مشتركة، أرسل معرّفها UUID في الترويسة x-ewasl-workspace-id:

curl https://app.ewasl.com/api/v1/posts \
  -H "Authorization: Bearer ewasl_abc123def456..." \
  -H "x-ewasl-workspace-id: 11111111-1111-4111-8111-111111111111"

لا تمنح هذه الترويسة الوصول وحدها. تتحقق eWasl في كل طلب من العضوية الحالية، وحالة مساحة العمل، وصلاحيات الدور، والعلامات التجارية المعيّنة، واستحقاق مالك المساحة. يعيد المعرّف غير الصالح 400، بينما يعيد الوصول الملغى أو غير الكافي 403. لا ينبغي إعادة محاولة أي منهما تلقائياً في مساحة عمل أخرى.

الصلاحيات

كل مفتاح محكوم بصلاحيات محدّدة. لن تنجح إلا العمليات التي تغطّيها صلاحيات المفتاح.

إن افتقر المفتاح إلى الصلاحية المطلوبة، تعيد الواجهة خطأ 403 Forbidden:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required permission: posts:create"
  }
}

استجابات الأخطاء

مثال استجابة 401

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Valid API key required. Include Authorization: Bearer ewasl_... header."
  }
}

أفضل ممارسات الأمان

• احفظ المفاتيح سرّيةً — لا تضع مفاتيح API في إدارة الإصدارات ولا تكشفها في جافاسكربت العميل. استخدم متغيّرات البيئة.
• أقل امتياز ممكن — امنح فقط الصلاحيات التي يحتاجها تطبيقك فعلاً.
• دوّر المفاتيح دورياً — ألغِ القديمة وأنشئ جديدة بانتظام، خصوصاً بعد تغيّر أعضاء الفريق.
• افصل المفاتيح — أنشئ مفاتيح مختلفة للبيئات المختلفة (تطوير، تجريب، إنتاج) وللتطبيقات المختلفة.
• راقب الاستخدام — تحقّق من طابع last_used_at على مفاتيحك في اللوحة لاكتشاف أي استخدام غير مصرّح.
• ألغِ المفاتيح المسرّبة — إن تسرّب مفتاح، ألغِه فوراً من اللوحة أو عبر نقطة إلغاء مفتاح.