المصادقة والمفاتيح
المفاتيح السرية، التجريبية والحقيقية، وكيف تحافظ عليها.
كل طلب يحمل مفتاحًا سريًا في ترويسة Authorization:
Authorization: Bearer mwg_sk_live_...إنشاء مفتاح
ينشئ المالكون والمديرون المفاتيح من موجود › الإعدادات › للمطورين. يمكنك إنشاء مفاتيح خلال الفترة
التجريبية المجانية، لكن الطلبات ترجع 402 plan_required حتى تشترك مساحة العمل في باقة مدفوعة.
- يظهر المفتاح كاملًا مرة واحدة عند إنشائه. يحتفظ موجود ببصمة منه فقط، لذا لا يمكن عرض مفتاح مفقود مرة أخرى: أنشئ مفتاحًا جديدًا وألغِ القديم.
- خصص لكل نظام مفتاحه («نظام الطلبات»، «Zapier»)، حتى تستطيع إلغاء أحدها دون إيقاف الباقي.
- المفتاح تابع لمساحة العمل، وليس للشخص الذي أنشأه.
- التدوير يصدر مفتاحًا جديدًا بالإعدادات نفسها، ويظل القديم يعمل 7 أيام.
الصلاحيات (scopes)
لكل مفتاح الصلاحيات التي تختارها عند إنشائه (أول اثنتين افتراضيًا):
| الصلاحية | تسمح بـ |
|---|---|
campaigns:send | POST /campaigns وPOST /campaigns/{id}/cancel. |
campaigns:read | GET /campaigns/{id} وGET /campaigns/{id}/recipients. |
templates:read | GET /templates. |
numbers:read | GET /numbers. |
webhooks:manage | GET /webhooks/deliveries. |
ويعمل GET /me بأي مفتاح.
المفاتيح التجريبية والحقيقية
| البادئة | الاستخدام |
|---|---|
mwg_sk_live_ | بيئة الإنتاج. يرسل رسائل واتساب حقيقية ويخصم من الرصيد. |
mwg_sk_test_ | التطوير. يفحص POST /campaigns الطلب كاملًا ثم يرد بـ 403 test_key_cannot_send. لا يُحفظ شيء. |
القراءة والإلغاء يعملان بالنوعين. ويخبرك GET /me بهوية المفتاح:
{
"workspace": { "id": "ws_2Hd8Qp", "name": "Aura Store" },
"key": {
"name": "Order system",
"prefix": "mwg_sk_live_7Lm3",
"kind": "secret",
"mode": "live",
"scopes": ["campaigns:send", "campaigns:read"]
}
}حماية المفاتيح
- احتفظ بالمفاتيح على الخادم، في متغير بيئة أو مدير أسرار. لا تضعها أبدًا في موقع ويب أو تطبيق جوال أو مستودع عام أو رسالة دعم.
- إذا احتمل تسرب مفتاح، فألغه فورًا من الإعدادات › للمطورين. المفاتيح الملغاة تفشل بالخطأ
invalid_api_key. - أي شخص يملك المفتاح يستطيع الإرسال باسمك. تعامل معه ككلمة مرور رقم واتساب الخاص بك.
الأخطاء
| HTTP | code | المعنى |
|---|---|---|
| 401 | invalid_api_key | المفتاح غير موجود أو غير صحيح أو ملغى أو منتهي. |
| 402 | plan_required | مساحة العمل لم تشترك في باقة مدفوعة بعد. |
| 403 | insufficient_scope | المفتاح لا يملك الصلاحية (details.missing). |
| 403 | publishable_key_not_allowed | مفتاح عام (mwg_pk_…) على هذه الواجهة. |
| 403 | workspace_unavailable | مساحة العمل موقوفة أو قيد الإغلاق. |
| 429 | rate_limited | تجاوزت 600 طلب في الدقيقة بهذا المفتاح. |
اطلع على الحالات والأخطاء لمعرفة كل الأخطاء.