# المصادقة والمفاتيح

كل طلب يحمل مفتاح API سريًّا في ترويسة `Authorization`:

```bash
curl https://api.saei.automize.sa/v1/me -H "Authorization: Bearer sk_live_..."
```

وتعمل أيضًا الترويسة `X-Api-Key: sk_live_...` للأدوات التي لا تستطيع ضبط `Authorization`. الطلبات عبر HTTPS فقط.

## مفاتيح التشغيل والاختبار {#modes}

| المفتاح | يبدأ بـ | ماذا يفعل |
|---|---|---|
| اختبار | `sk_test_` | كل شيء محاكاة: لا تصل الرسائل إلى واتساب، ولا شيء يُحتسب في الفوترة، ولا تستقبل الأحداث إلا نقاط الاستقبال الخاصة بوضع الاختبار. |
| تشغيل | `sk_live_` | رسائل حقيقية إلى عملاء حقيقيين عبر أرقامك المربوطة. |

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

## الصلاحيات {#scopes}

لا يستطيع المفتاح إلا ما تسمح به صلاحياته. كل نقطة في المرجع تذكر الصلاحية التي تحتاجها، وبدونها تُرجع الواجهة `403 insufficient_scope` وتذكر الصلاحية الناقصة في `required_scope`.

| الصلاحية | تسمح بـ |
|---|---|
| `messages:send` | إرسال الرسائل واستخدام أدوات وضع الاختبار |
| `messages:read` | قراءة الرسائل وحالتها |
| `webhooks:read` / `webhooks:write` | عرض وإدارة نقاط الاستقبال وعمليات الإرسال |
| `templates:read` | قراءة القوالب *(قريبًا)* |
| `contacts:read` / `contacts:write` | قراءة وإدارة جهات الاتصال *(قريبًا)* |

عند إنشاء المفتاح يمكنك اختيار مجموعة جاهزة (**وصول كامل**، **المراسلة**، **قراءة فقط**) أو اختيار الصلاحيات واحدة واحدة. امنح كل تكامل أقل ما يحتاجه.

## حماية المفاتيح {#safety}

- يظهر المفتاح كاملًا **مرة واحدة** عند إنشائه، ونحن لا نخزّن إلا بصمته.
- احفظ المفاتيح في متغيرات البيئة أو مدير الأسرار، ولا تضعها أبدًا في كود المتصفح أو تطبيق جوال أو مستودع كود.
- أنشئ مفتاحًا لكل تكامل، لتلغي أحدها دون أن يتعطل الباقي.
- ألغِ المفتاح فور الشك في تسرّبه: **المطورون ← مفاتيح API ← إلغاء**. يتوقف فورًا (`api_key_revoked`).
- لا تُنشأ المفاتيح إلا من البوابة، ولا يمكن إنشاؤها عبر الواجهة، لذا لا يستطيع مفتاح مسرّب إنشاء مفاتيح أخرى.

## الباقات {#plans}

مفاتيح الاختبار تعمل في كل الباقات. أما الوصول الحي للواجهة فجزء من الباقات التي تشمله، وإن لم تشمله باقتك تُرجع الطلبات الحية `api_access_not_in_plan`.