المصادقة

مفاتيح 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
  }'

الصلاحيات

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

إن افتقر المفتاح إلى الصلاحية المطلوبة، تعيد الواجهة خطأ 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 على مفاتيحك في اللوحة لاكتشاف أي استخدام غير مصرّح.
• ألغِ المفاتيح المسرّبة — إن تسرّب مفتاح، ألغِه فوراً من اللوحة أو عبر نقطة إلغاء مفتاح.