المصادقة #

يجب أن يحمل كل طلب API مفتاح API الخاص بك حتى يعرف Your AI Connector هويتك والحساب الذي يجب العمل عليه. يمكنك إرسال المفتاح بأربع طرق مختلفة — جميعها تعمل على كل نقطة نهاية تقبل المصادقة عبر مفتاح API، لذا اختر الطريقة التي تناسب إعداداتك.

الوصول إلى API هو ميزة مدفوعة. إذا كانت خطتك لا تتضمن ذلك، فسيتم رفض الطلبات بـ 403 حتى لو كان المفتاح نفسه صالحاً — راجع بوابة الميزات المدفوعة أدناه. لإنشاء مفتاح، راجع الوصول إلى API.

HTTPS فقط. يجب أن تستخدم جميع الطلبات اتصالاً آمناً. يتم رفض طلبات HTTP العادية قبل أن تبدأ المصادقة حتى.

نظرة سريعة على الطرق الأربع #

عند وجود أكثر من طريقة، تكون الأولوية لمعامل الاستعلام، ثم ترويسة X-API-Key، ثم رمز Bearer. عملياً، أنت ترسل واحدة فقط.

1. معامل الاستعلام — ?apiKey= #

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

cURL

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()

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

2. ترويسة X-API-Key #

أرسل المفتاح في ترويسة مخصصة. هذا يبقيه خارج عنوان URL وهو الخيار الموصى به لبيئة الإنتاج.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

3. ترويسة Authorization: Bearer #

يمكنك أيضاً تمرير المفتاح كرمز حامل (bearer token) قياسي. هذا مفيد عندما يكون لدى عميل HTTP أو إطار العمل الخاص بك دعم مدمج لترويسات Authorization.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

تُميّز واجهة برمجة التطبيقات (API) مفتاحك عن رمز تسجيل الدخول تلقائياً، لذا تعمل هذه الطريقة تماماً مثل X-API-Key.

4. رمز معرف Firebase (للطرف الأول فقط) #

إذا كنت تبني تطبيقاً من الطرف الأول يقوم بتسجيل دخول المستخدمين من خلال تسجيل دخول Your AI Connector الخاص، يمكنك تمرير رمز معرف Firebase الخاص بالمستخدم الذي قام بتسجيل الدخول كرمز حامل (bearer token) بدلاً من مفتاح API:

Authorization: Bearer <Firebase ID token>

يتم التحقق من الرمز في كل طلب ويتم ربطه بالحساب الذي قام بتسجيل الدخول. هذه الطريقة مخصصة فقط لجلسات تطبيقات الطرف الأول — لا يمكنك إنشاء هذه الرموز من تكامل خارجي، ولا توجد طريقة للحصول عليها دون المرور بعملية تسجيل الدخول العادية للتطبيق. بالنسبة للتكاملات من خادم إلى خادم وتكاملات الطرف الثالث، استخدم مفتاح API (الطرق 1–3).

متى تستخدم أياً منها #

• الاختبارات السريعة والبرامج النصية لمرة واحدة → معامل الاستعلام (?apiKey=). الأسرع في الكتابة، ويعمل في المتصفح.
• تكاملات الإنتاج وطلبات الخادم إلى الخادم → X-API-Key أو Authorization: Bearer YOUR_API_KEY. تبقي المفتاح بعيداً عن عناوين URL والسجلات.
• تطبيقات الطرف الأول مع مستخدم Your AI Connector مسجل الدخول → Authorization: Bearer <Firebase ID token>.

نطاقات المفاتيح #

يحتوي حسابك على مفتاح API رئيسي واحد — وهو الموجود تحت الإعدادات ← عمليات التكامل ← مفتاح API. يتمتع هذا المفتاح بوصول كامل إلى كل ما يمكن للحساب القيام به.

يمكنك أيضاً إنشاء مفاتيح ذات نطاق محدد (scoped keys): وهي مفاتيح مسماة لا تصل إلا إلى أجزاء API التي تختارها، على سبيل المثال مفتاح للقراءة فقط يقتصر على التحليلات (Analytics) للوحة تحكم التقارير. يتم إرسال المفتاح ذو النطاق المحدد تماماً مثل المفتاح الرئيسي (بأي من الطرق 1–3 أعلاه)، ولكن يتم التحقق منه مقابل أذوناته الخاصة في كل طلب:

• يتم رفضه خارج المناطق المسموح بها. عملية كتابة باستخدام مفتاح للقراءة فقط، أو استدعاء لقسم لم يُمنح المفتاح صلاحية الوصول إليه، يعود كـ 403 — key_read_only أو key_scope_denied في حقل error_code. التحقق صارم بشكل متعمد: أي شيء ليس بوضوح داخل المناطق المسموح بها للمفتاح يتم رفضه بدلاً من السماح بمروره، لذا إذا رأيت أحد تلك الـ 403، فهذا يعني ببساطة أن المفتاح لا يغطي نقطة النهاية (endpoint) تلك.
• لديه ميزانية خاصة بحدود المعدل (rate-limit). يتم احتساب المفتاح ذو النطاق المحدد بشكل منفصل عن مفتاحك الرئيسي، لذا فإن لوحة التحكم المزدحمة التي تستخدم مفتاحاً ذا نطاق محدد لا يمكنها استهلاك المخصصات التي تعتمد عليها عمليات التكامل الأخرى الخاصة بك. أنت تختار تلك الميزانية لكل دقيقة عند إنشاء المفتاح.
• لا يمكنه إدارة مفاتيح API. فقط مالك الحساب — عند تسجيل الدخول، أو باستخدام المفتاح الرئيسي — يمكنه سرد المفاتيح أو إنشائها أو تعديلها أو تدويرها أو إلغاؤها. لا يمكن للمفتاح ذي النطاق المحدد أبداً إنشاء مفتاح أوسع صلاحية لنفسه.

راجع مفاتيح API لمعرفة كيفية إنشاء وتعديل وإلغاء المفاتيح ذات النطاق المحدد.

بوابة الميزات المدفوعة #

الوصول إلى واجهة برمجة التطبيقات (API) هو ميزة مدفوعة. عندما لا تتضمن خطتك هذه الميزة، يتم رفض الطلب الذي يحتوي على مفتاح صالح بخلاف ذلك بالرمز 403:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

If you see this, check your plan or contact hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

الحفاظ على أمان مفتاحك #

• عامل المفتاح ككلمة مرور. يمنح مفتاحك الرئيسي وصولاً كاملاً إلى حسابك. إذا كنت بحاجة إلى تسليم مفتاح لأداة أو شخص يحتاج فقط إلى جزء منه، فقم بإنشاء مفتاح ذي نطاق محدد بدلاً من ذلك — راجع نطاقات المفاتيح.
• احتفظ به في جانب الخادم (server-side). لا تقم أبداً بتضمينه في JavaScript الخاص بالمتصفح، أو حزمة تطبيق جوال، أو أي كود يمكن للمستخدم النهائي قراءته.
• قم بتخزينه في مدير أسرار (secret manager) أو في إعدادات جانب الخادم، وليس في التحكم في المصدر (source control).
• قم بتدويره إذا تسرب. قم بإنشاء مفتاح جديد من لوحة التحكم أو استدعِ POST https://api.youraiconnector.com/v1/api-keys/rotate — هذا يؤدي فوراً إلى إبطال المفتاح القديم. راجع مفاتيح API.
• استخدم HTTPS دائماً بحيث يتم تشفير المفتاح أثناء النقل.

الخطوات التالية #

• البدء — طلبك الأول وأدلة الموارد.
• الأخطاء والترقيم — التعامل مع الإخفاقات والتنقل بين صفحات النتائج.
• مفاتيح API — تغيير مفتاحك، أو إلغاؤه، أو التحقق من استخدامه.