المصادقة

استخدم مفتاح API لخادمك الخلفي أو لأتمتة أعمالك. واستخدم OAuth عندما يطلب تطبيقك من مستخدمين آخرين في Make Agent Fast منحه حق الوصول. يستدعي النوعان من بيانات الاعتماد موارد /api/v1 نفسها، ويخضعان للنطاقات نفسها، وصلاحيات الخطة، وعزل المستأجرين، وحدود المعدّل.

مفاتيح API#

يتطلب إنشاء مفتاح API عام واستخدامه وجود خطة مدفوعة نشطة.

1. افتح لوحة التحكم ← الإعدادات ← المطوّرون.
2. أدخل اسمًا يحدد الخدمة والبيئة، مثل Production lead export.
3. حدّد أقل النطاقات التي تحتاج إليها الخدمة.
4. اختر مدة الصلاحية: 30 يومًا، أو 90 يومًا، أو سنة واحدة، أو بلا انتهاء.
5. أنشئ المفتاح، وانسخ القيمة maf_live_... فورًا.

يخزّن Make Agent Fast تجزئة SHA-256 بدلًا من نص عادي يمكن استرجاعه. وتعرض لوحة التحكم لاحقًا بادئة آمنة للمفتاح، والنطاقات، وتاريخ الانتهاء، ووقت آخر استخدام، وحالة الإلغاء.

Authorization: Bearer maf_live_...

أرسل الترويسة من شيفرة الخادم:

curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

يؤدي غياب بيانات الاعتماد إلى الاستجابة 401 authentication_required. أما المفاتيح غير الصالحة أو المنتهية أو الملغاة فتُرجع 401 invalid_api_key. وإذا لم تعد الخطة المدفوعة نشطة في حساب المفتاح، فتُرجع الاستجابة 403 subscription_required.

تدوير المفتاح أو إلغاؤه#

أنشئ مفتاحًا بديلًا قبل إلغاء المفتاح القديم. انشر المفتاح البديل، وأرسل طلبًا فعليًا، وتحقق من x-request-id الخاص به، ثم انقر إلغاء على المفتاح القديم. الإلغاء فوري ولا يمكن التراجع عنه.

في إعدادات المطوّرون، يتيح لك تعديل تغيير اسم المفتاح النشط ونطاقاته؛ ويسري التغيير فورًا على المفتاح نفسه. أما مدة الصلاحية والرمز فلا يمكن تغييرهما، لذا أنشئ مفتاحًا بديلًا للحصول على مدة صلاحية جديدة أو رمز مُدوَّر.

تطبيقات OAuth#

يُستخدم OAuth للبرمجيات التي تتصل بحسابات يملكها مستخدمون آخرون في Make Agent Fast. ويعتمد على Authorization Code مع PKCE (S256)، ولا يُصدر سرّ عميل ولا يتطلبه. معرّف العميل (client ID) عام؛ أما أكواد التفويض، ورموز الوصول، ورموز التحديث، وPKCE verifier فهي بيانات حساسة.

1. سجّل التطبيق#

افتح لوحة التحكم ← الإعدادات ← المطوّرون ← تطبيقات OAuth. ثم أضف:

• اسم التطبيق بطول من 2 إلى 100 حرف.
• ما بين 1 و10 عناوين URL دقيقة لإعادة التوجيه.
• الحد الأقصى للنطاقات التي يجوز لتطبيقك طلبها.

يجب أن تستخدم عناوين URL لإعادة التوجيه في الإنتاج HTTPS، ولا يجوز أن تتضمن بيانات اعتماد أو أجزاء (fragments). ويجب أن يطابق URI الكامل إحدى القيم المسجّلة أثناء التفويض وتبادل الرمز. تكون حالة التطبيقات المقدَّمة حديثًا pending، ولا يعمل التفويض إلا بعد مراجعة التطبيق ووسمه approved.

يراجع مالك المنصة معرّفات العملاء المعلّقة عبر سير العمل المدقَّق oauth:review. احتفظ بمعرّف العميل الظاهر بعد الإرسال؛ إذ تظهر حالته في صفحة المطوّرين، وتتضمن التطبيقات المرفوضة قرار المراجعة قبل أن يمكن إعادة إرسالها.

2. أنشئ قيم PKCE#

أنشئ verifier جديدًا لكل محاولة تفويض، واحتفظ به في الجلسة المحمية قصيرة الأمد نفسها التي تحتفظ فيها بالقيمة state.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");

يجب أن يتكون verifier من 43 إلى 128 حرفًا من أحرف PKCE الآمنة في عناوين URL. ولا يُقبل سوى code_challenge_method=S256.

3. أعد توجيه المستخدم للموافقة#

https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

يسجّل المستخدم الدخول، ويراجع النطاقات المطلوبة، ثم يسمح بالوصول أو يرفضه. عند النجاح، يعيد Make Agent Fast التوجيه إلى URI المسجّل نفسه تمامًا مع code وقيمة state الأصلية. وعند الرفض، يرسل error=access_denied مع قيمة state الأصلية إن كانت قد أُرسلت.

ارفض استدعاء الرجوع (callback) إذا لم تطابق قيمة state تمامًا القيمة المخزّنة لجلسة المتصفح تلك.

4. بادل كود التفويض#

ينتهي كود التفويض بعد 10 دقائق، ولا يمكن استخدامه إلا مرة واحدة.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}

يظل رمز الوصول صالحًا لمدة ساعة واحدة. ويظل رمز التحديث صالحًا حتى 90 يومًا ما لم يُدوَّر أو يُلغَ قبل ذلك.

5. دوّر رمز التحديث#

يؤدي كل تحديث ناجح إلى إلغاء رمز التحديث المُرسَل ورمز الوصول السابق المرتبط به، ثم يُرجع زوجًا جديدًا. احفظ الزوج الجديد بشكل ذرّي قبل التخلص من حالة الاستجابة السابقة.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

يؤدي إعادة استخدام كود تفويض أو رمز تحديث سبق تدويره إلى الاستجابة invalid_grant. وتُرجع نقطة نهاية رمز OAuth استجابات بصيغة OAuth هي { "error", "error_description" } بدلًا من غلاف الأخطاء الخاص بواجهة API العامة، وتسمح بـ 30 طلب رمز لكل عنوان IP للمتصل في الدقيقة.

لا تصادق أبدًا على طلبات الإدارة في شيفرة المتصفح#

لا تضع مفتاح API سريًا أو رمز وصول أو رمز تحديث في مكوّنات React على جهة العميل، أو في JavaScript ثابت، أو في الويب على الجوال، أو في Webflow أو Framer أو Wix أو Shopify Liquid. استخدم خادمك الخلفي المصادَق عليه. يعتمد تضمين الموقع العام على معرّف موقع (site slug) غير سرّي وعلى قائمة سماح للأصول (origins)، لا على بيانات اعتماد واجهة الإدارة البرمجية.

راجع بيانات الاعتماد والرموز والنطاقات والأخطاء والبدء السريع مع API.