واجهة برمجة تطبيقات مفاتيح API

تتيح لك نقاط النهاية هذه إدارة مفاتيح API الخاصة بحسابك برمجياً. تعمل جميعها على مفاتيح الحساب الذي يقوم بالاستدعاء فقط.

هناك نوعان من المفاتيح، وهما موجودان في مسارات منفصلة:

مفتاحك الرئيسي — هو المفتاح الوحيد ذو الوصول الكامل الموجود تحت الإعدادات ← عمليات التكامل ← مفتاح API. يمكنك الاطلاع على معاينته المقنعة، والتحقق من استخدام حد المعدل الخاص بك، أو تدويره، أو إلغاؤه. هذه هي نقاط النهاية /api-keys/current و /api-keys/rotate و /api-keys/usage أدناه.
المفاتيح ذات النطاق المحدود (Scoped keys) — مفاتيح إضافية مسمّاة تنشئها لمهمة محددة، حيث يقتصر كل منها على أجزاء API التي تختارها. هذه هي نقاط النهاية /api-keys و /api-keys/{id} تحت المفاتيح ذات النطاق المحدود. لا يتغير أي شيء يتعلق بمفتاحك الرئيسي عند إنشاء أحد هذه المفاتيح؛ وتستمر عمليات التكامل الحالية في العمل دون مساس.

جميع المسارات أدناه نسبية إلى عنوان URL الأساسي لواجهة برمجة التطبيقات:

https://api.youraiconnector.com/v1

يجب مصادقة كل طلب. راجع المصادقة لمعرفة الطرق الأربع المقبولة. تستخدم الأمثلة هنا رأس X-API-Key (ونموذج معلمة استعلام واحد لـ cURL).

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

الحصول على البيانات الوصفية للمفتاح الحالي

يعيد مفتاحك النشط: المفتاح الكامل في api_key عند وجود نسخة قابلة للاسترداد، أو معاينة مقنعة (أول 4 أحرف وآخر 4 أحرف)، وتاريخ إنشائه عند توفره. api_key هو null للمفاتيح التي تم إنشاؤها قبل الاحتفاظ بنسخ قابلة للاسترداد — قم بتدوير المفتاح مرة واحدة وسيصبح بالإمكان عرض المفتاح الجديد مرة أخرى لاحقاً.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

الاستجابة

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

إذا لم يكن للحساب مفتاح API، تكون الاستجابة 404 مع { "success": false, "error": "No API key found for this account" }.

الحصول على استخدام حد المعدل

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

GET /api-keys/usage

cURL

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

JavaScript

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

Python

import requests

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

الاستجابة

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

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

تدوير المفتاح

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

POST /api-keys/rotate

يتم عرض المفتاح الجديد مرة واحدة فقط. يتم إرجاعه في هذه الاستجابة ولا يمكن استرداده بالكامل بعد ذلك — قم بتخزينه بشكل آمن في اللحظة التي تتلقاه فيها. يتوقف المفتاح السابق عن العمل بمجرد نجاح هذا الاستدعاء، لذا قم بتحديث كل عملية تكامل كانت تستخدمه.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

الاستجابة

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

إلغاء المفتاح

يحذف مفتاح API الخاص بحسابك بشكل دائم. الإلغاء فوري: يتم رفض كل طلب لاحق يستخدم المفتاح المُلغى — بما في ذلك عمليات التكامل مثل Make أو Zapier أو البرامج النصية المخصصة — مع 401. لاستعادة الوصول إلى API بعد ذلك، قم بإنشاء مفتاح جديد من إعدادات حسابك أثناء تسجيل الدخول إلى التطبيق.

DELETE /api-keys/current

لا يوجد تراجع. على عكس التدوير، لا يمنحك الإلغاء مفتاحاً بديلاً. قم بالإلغاء فقط عندما تنوي إيقاف الوصول إلى API (على سبيل المثال، مفتاح مسرب لا يمكنك استبداله على الفور).

cURL

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

JavaScript

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

Python

import requests

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

الاستجابة

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

إذا لم يكن لدى الحساب مفتاح لإلغائه، تكون الاستجابة 404.

المفاتيح ذات النطاق المحدود

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

ينتقل القيد مع المفتاح نفسه، لذا لا يمكن لأي شخص يحمله القيام إلا بما سمحت به عند إنشائه.

ما يمكنك تقييده

الحقل	المعنى
`read_only`	`true` (الافتراضي) يعني السماح بطلبات القراءة فقط. يتم رفض أي إنشاء أو تحديث أو حذف.
`tags`	قائمة أقسام API التي قد يستخدمها المفتاح، مكتوبة بنفس أسماء الأقسام التي تراها في هذه المستندات وفي مستكشف API — `Analytics`، `Campaigns`، `Contacts`، `Messages`، `Appointments`، وهكذا. القائمة الفارغة تعني كل الأقسام.
`sub_account_ids`	الحسابات المُدارة التي يمكن للمفتاح العمل عليها. الفراغ يعني حسابك الخاص فقط؛ و `["*"]` يعني أي حساب تديره فعلياً. لا تزال الملكية يتم التحقق منها في كل طلب.
`rate_limit_per_min`	الطلبات في الدقيقة لهذا المفتاح، تُحسب ضمن ميزانيته الخاصة حتى لا يستهلك مخصصات عمليات التكامل الأخرى الخاصة بك. القيمة الافتراضية هي `60`، ولا يمكن ضبطها فوق `300`.

يمكنك أيضاً منح المفتاح تاريخ expires_at (بتنسيق ISO 8601، ويجب أن يكون في المستقبل). بعد تلك اللحظة، يتوقف المفتاح عن العمل من تلقاء نفسه. اتركه فارغاً ولن تنتهي صلاحية المفتاح أبداً حتى تقوم بإلغائه.

الرفض هو الحالة الافتراضية عند عدم المطابقة. إذا وقع الطلب خارج نطاق ما يسمح به المفتاح، يتم رفضه بدلاً من السماح بمروره: عملية كتابة باستخدام مفتاح للقراءة فقط تُرجع 403 مع error_code: "key_read_only"، وأي شيء خارج الأقسام المسموح بها للمفتاح يُرجع 403 مع error_code: "key_scope_denied". إذا تلقى مفتاح ذو نطاق محدود 403 غير متوقع، فهذا يعني ببساطة أن نقطة النهاية التي استدعيتها ليست ضمن نطاقاته — قم بتوسيع نطاق المفتاح أو استخدم مفتاحك الرئيسي.

مالك الحساب فقط هو من يدير المفاتيح. تتطلب نقاط النهاية الأربع هذه مفتاحك الرئيسي، أو جلسة مالك في التطبيق. لا يمكن للمفتاح ذي النطاق المحدود أبداً سرد المفاتيح أو إنشائها أو تعديلها أو إلغاؤها — بما في ذلك نفسه — لذا لا يمكن أبداً استخدام مفتاح مقيد لإنشاء مفتاح أوسع صلاحية. محاولة القيام بذلك تُرجع 403 مع error_code: "key_scope_denied". ولنفس السبب، API Keys ليس قسماً يمكنك منحه: طلب ذلك يُرجع 400 مع error_code: "invalid_scopes".

سرد المفاتيح ذات النطاق المحدود

يُرجع المفاتيح ذات النطاق المحدود الخاصة بالحساب، مرتبة من الأحدث إلى الأقدم (حتى 200 مفتاح)، بما في ذلك المفاتيح الملغاة حتى تتمكن من معرفة ما تم سحبه ومتى. يتم إرجاع المعاينات المقنعة فقط — تظهر قيمة المفتاح ذي النطاق المحدود مرة واحدة فقط، عند الإنشاء، ولا يمكن استردادها بعد ذلك أبداً.

GET /api-keys

cURL

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

الاستجابة

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

إنشاء مفتاح ذو نطاق محدود

ينشئ مفتاحاً ذا نطاق جديد ويعيد قيمته مرة واحدة.

POST /api-keys

يتم عرض المفتاح مرة واحدة فقط. يظهر في هذا الرد ولا يظهر في أي مكان آخر على الإطلاق — لا توجد طريقة للاطلاع عليه مرة أخرى بعد ذلك. قم بتخزينه فور استلامه. إذا فقدته، قم بإلغائه وإنشاء مفتاح آخر.

حقول النص (Body fields) — جميعها اختيارية:

الحقل	النوع	ملاحظات
`label`	string	اسمك الخاص للمفتاح، يظهر في القائمة وفي الإعدادات.
`scopes`	object	الحقول الأربعة في الجدول أعلاه. اترك الكائن بالكامل فارغاً وستحصل على الإعداد الافتراضي الآمن: للقراءة فقط، مقتصر على `Analytics`، لحسابك الخاص فقط، 60 طلباً في الدقيقة.
`expires_at`	ISO 8601 date	تاريخ انتهاء اختياري، يجب أن يكون في المستقبل.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

الاستجابة — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

بضع تفاصيل تستحق المعرفة عند البناء باستخدام هذا:

حذف scopes ليس مثل إرسال قائمة tags فارغة. اترك scopes فارغاً تماماً وستحصل على الإعداد الافتراضي الآمن (للقراءة فقط، Analytics فقط). أرسل "tags": [] عن قصد وقد يستخدم المفتاح كل قسم — يُقرأ ذلك كطلب متعمد للحصول على مفتاح غير مقيد.
يبقى read_only كما هو true ما لم ترسل false صراحةً. لا يمكن لخطأ مطبعي أو علامة مفقودة أن ينتج عن طريق الخطأ مفتاحاً يمكنه الكتابة.

تحديث مفتاح ذي نطاق

يغير تسمية المفتاح، أو نطاقاته، و/أو تاريخ انتهاء صلاحيته. أرسل أي مزيج من الثلاثة؛ إرسال لا شيء منها يعيد 400.

PATCH /api-keys/{id}

إن {id} هو id الخاص بالمفتاح من القائمة (قيمة key_...)، وليس المفتاح نفسه أبداً.

يتم استبدال النطاقات، وليس دمجها. أي شيء ترسله يصبح مجموعة الأذونات الكاملة للمفتاح. هذا مقصود: تضييق نطاق مفتاح لا يمكن أبداً أن يترك الوصول الأوسع القديم في مكانه دون ملاحظة. أرسل دائماً كائن scopes الكامل الذي تريده، وليس فقط الحقل الذي تقوم بتغييره.

قيمة المفتاح لا تتغير أبداً. لا يوجد تدوير في مكانه لمفتاح ذي نطاق — لتدويره، أنشئ مفتاحاً جديداً وألغِ القديم، بحيث لا يمكن أبداً تغيير وصول بيانات الاعتماد تحت تكامل لا يزال يحتفظ به.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

الاستجابة

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

إذا لم يكن هناك مفتاح بهذا المعرف (id) في حسابك، تكون الاستجابة 404.

إبطال مفتاح ذي نطاق محدد

يتم الإبطال فوراً: سيتم رفض الطلب التالي مباشرةً الذي يستخدم ذلك المفتاح مع 401. لن يتأثر مفتاحك الرئيسي أو أي مفتاح آخر ذو نطاق محدد.

DELETE /api-keys/{id}

يبقى المفتاح في قائمتك موسوماً بـ "revoked": true، لذا ستحتفظ بسجل لما كان موجوداً وما كان يمكنه الوصول إليه. إبطال مفتاح تم إبطاله بالفعل ينجح ولا يغير شيئاً.

cURL

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

الاستجابة

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

أخطاء واجهة برمجة تطبيقات مفاتيح API

تُرجع نقاط نهاية مفاتيح API غلاف الخطأ القياسي:

{
  "success": false,
  "error": "No API key found for this account"
}

في نقطة نهاية مفتاح API، يؤدي فقدان المفتاح أو كونه غير صالح إلى إرجاع 401، بينما يؤدي وجود حساب ليس لديه مفتاح مسجل إلى إرجاع 404. الرموز المشتركة التي يمكن أن تُرجعها أي نقطة نهاية — 400، و403 (خطتك لا تتضمن الوصول إلى واجهة برمجة التطبيقات)، و429 (حد المعدل)، و500 — مدرجة مع إرشادات إعادة المحاولة في الأخطاء والترقيم.

تضيف نقاط نهاية المفاتيح ذات النطاق المحدد بضعة رموز مسماة في حقل error_code حتى تتمكن من التمييز بين الحالات:

`error_code`	الحالة	ما الذي حدث
`key_read_only`	`403`	حاول مفتاح للقراءة فقط إجراء عملية كتابة.
`key_scope_denied`	`403`	المفتاح غير مسموح به في نقطة النهاية تلك أو ذلك الحساب المُدار — أو حاول مفتاح ذو نطاق محدد إدارة مفاتيح API، وهو أمر غير مسموح به أبداً.
`invalid_scopes`	`400`	تضمنت النطاقات المطلوبة قسم `API Keys`. لا يمكن للمفاتيح إدارة مفاتيح أخرى.
`404`	`404`	لا يوجد مفتاح بهذا المعرف في حسابك.

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

المصادقة — الطرق الأربع لمصادقة الطلب، وكيفية فرض نطاقات المفاتيح.
الأخطاء وحدود المعدل — رموز الحالة وحد 300 طلب/دقيقة.

واجهة برمجة تطبيقات مفاتيح API #

الحصول على البيانات الوصفية للمفتاح الحالي #

الحصول على استخدام حد المعدل #

تدوير المفتاح #

إلغاء المفتاح #

المفاتيح ذات النطاق المحدود #

سرد المفاتيح ذات النطاق المحدود #

إنشاء مفتاح ذو نطاق محدود #

تحديث مفتاح ذي نطاق #

إبطال مفتاح ذي نطاق محدد #

أخطاء واجهة برمجة تطبيقات مفاتيح API #

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

واجهة برمجة تطبيقات مفاتيح API

الحصول على البيانات الوصفية للمفتاح الحالي

الحصول على استخدام حد المعدل

تدوير المفتاح

إلغاء المفتاح

المفاتيح ذات النطاق المحدود

سرد المفاتيح ذات النطاق المحدود

إنشاء مفتاح ذو نطاق محدود

تحديث مفتاح ذي نطاق

إبطال مفتاح ذي نطاق محدد

أخطاء واجهة برمجة تطبيقات مفاتيح API

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