Source: https://ailoot.ai/docs/ar/cabinet/keys/
Canonical: https://ailoot.ai/docs/ar/cabinet/keys/
Language: ar

[API لوحة الحساب](https://ailoot.ai/docs/ar/) 

# مفاتيح API

[Markdown](https://ailoot.ai/docs/ar/cabinet/keys/index.md)

الطرق وحقول الطلبات والردود.

يضم القسم 5 طرق. افتح الطريقة لعرض شروط الوصول وحقول الطلب والرد.

| الطريقة والمسار | الوصف | الوصول |
| --- | --- | --- |
| `GET /api/v1/keys` | القائمة — مفاتيح API | توكن لوحة الحساب |
| `POST /api/v1/keys` | إنشاء مفتاح API | توكن لوحة الحساب |
| `DELETE /api/v1/keys/:id` | الحذف — مفاتيح API | توكن لوحة الحساب |
| `GET /api/v1/keys/:id` | الاسترجاع بالمعرّف — مفاتيح API | توكن لوحة الحساب |
| `PUT /api/v1/keys/:id` | تعديل مفتاح API | توكن لوحة الحساب |

**GET /api/v1/keys** — القائمة — مفاتيح API

الوصول: توكن لوحة الحساب

GET`/api/v1/keys`

قراءة؛ يُؤخذ ID من رد سابق لك

```bash
curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"
```

## معاملات الاستعلام

| الحقل | النوع | مطلوب | التحقق / الوصف |
| --- | --- | --- | --- |
| `sort_by` | `string` | لا | ؛ القيمة الافتراضية: created\_at |
| `sort_order` | `string` | لا | ؛ القيمة الافتراضية: desc |
| `search` | `string` | لا |  |
| `status` | `string` | لا |  |
| `page` | `integer` | لا | ؛ القيمة الافتراضية: 1; positive; page\_size/limit \<=1000 |
| `page_size` | `integer` | لا | ؛ القيمة الافتراضية: 20; positive; page\_size/limit \<=1000 |
| `limit` | `integer` | لا | ؛ القيمة الافتراضية: 20; positive; page\_size/limit \<=1000 |

لا يلزم جسم للطلب. أرسل المعاملات المذكورة أعلاه في URL.

## الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: `APIKey`. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}
```

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

**POST /api/v1/keys** — إنشاء مفتاح API

الوصول: توكن لوحة الحساب

POST`/api/v1/keys`

## حقول JSON / النموذج

| الحقل | النوع | مطلوب | التحقق / الوصف |
| --- | --- | --- | --- |
| `name` | `string` | نعم | required |
| `custom_key` | `string` | لا | ؛ قيمة مخصصة اختيارية للمفتاح؛ يمكن أن تكون null |
| `ip_whitelist` | `array` | لا | ؛ قائمة عناوين IP المسموح بها |
| `ip_blacklist` | `array` | لا | ؛ قائمة عناوين IP المحظورة |
| `quota` | `number` | لا | ؛ حد إنفاق المفتاح بالدولار USD؛ يمكن أن يكون null |
| `expires_in_days` | `integer` | لا | ؛ مدة الصلاحية بالأيام؛ يمكن أن تكون null |
| `rate_limit_5h` | `number` | لا | ؛ يمكن أن يكون null |
| `rate_limit_1d` | `number` | لا | ؛ يمكن أن يكون null |
| `rate_limit_7d` | `number` | لا | ؛ يمكن أن يكون null |

قالب جسم الطلب

```json
{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}
```

يشير PLACEHOLDER إلى مدخلاتك ونوعها. استبدل القيم وأبقِ الحقول الاختيارية المطلوبة فقط؛ لا ترسل العلامات النصية بدلاً من الأرقام أوboolean أوالكائنات أوالمصفوفات.

مخطط الطلب: `CreateAPIKeyRequest`

## الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: `APIKey`. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}
```

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: تغيّر العملية الحالة أو تواصل مصادقة لمرة واحدة؛ يصف المثال العقد ولا يتم تنفيذه.

ملاحظات: يدعم Idempotency-Key؛ وتعيد المحاولة المكررة الرد المحفوظ مع X-Idempotency-Replayed.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

تغيّر الطريقة البيانات. تكون إعادة الإرسال آمنة فقط إذا ذُكر Idempotency-Key لهذه الطريقة. إذا فُقد الرد، فتحقق أولاً من النتيجة (مثل قائمة المفاتيح)، ثم قرر ما إذا كنت ستعيد الطلب.

**DELETE /api/v1/keys/:id** — الحذف — مفاتيح API

الوصول: توكن لوحة الحساب

DELETE`/api/v1/keys/:id`

## معاملات المسار

| الحقل | النوع | مطلوب | التحقق / الوصف |
| --- | --- | --- | --- |
| `id` | `integer` | نعم |  |

لا يلزم جسم للطلب.

## الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخطط الرد؛ القيم تمثيلية

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}
```

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: تغيّر العملية الحالة أو تواصل مصادقة لمرة واحدة؛ يصف المثال العقد ولا يتم تنفيذه.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

تغيّر الطريقة البيانات. تكون إعادة الإرسال آمنة فقط إذا ذُكر Idempotency-Key لهذه الطريقة. إذا فُقد الرد، فتحقق أولاً من النتيجة (مثل قائمة المفاتيح)، ثم قرر ما إذا كنت ستعيد الطلب.

**GET /api/v1/keys/:id** — الاسترجاع بالمعرّف — مفاتيح API

الوصول: توكن لوحة الحساب

GET`/api/v1/keys/:id`

قراءة؛ يُؤخذ ID من رد سابق لك

```bash
curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"
```

## معاملات المسار

| الحقل | النوع | مطلوب | التحقق / الوصف |
| --- | --- | --- | --- |
| `id` | `integer` | نعم |  |

لا يلزم جسم للطلب. أرسل المعاملات المذكورة أعلاه في URL.

## الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: `APIKey`. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}
```

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

**PUT /api/v1/keys/:id** — تعديل مفتاح API

الوصول: توكن لوحة الحساب

PUT`/api/v1/keys/:id`

## معاملات المسار

| الحقل | النوع | مطلوب | التحقق / الوصف |
| --- | --- | --- | --- |
| `id` | `integer` | نعم |  |

## حقول JSON / النموذج

| الحقل | النوع | مطلوب | التحقق / الوصف |
| --- | --- | --- | --- |
| `name` | `string` | لا |  |
| `status` | `string` | لا | omitempty,oneof=active inactive |
| `ip_whitelist` | `array` | لا | ؛ عناوين IP المسموح بها: لا تغيّر null القائمة، وتُفرغها المصفوفة الفارغة؛ يمكن أن تكون null |
| `ip_blacklist` | `array` | لا | ؛ عناوين IP المحظورة: لا تغيّر null القائمة، وتُفرغها المصفوفة الفارغة؛ يمكن أن تكون null |
| `quota` | `number` | لا | ؛ حد إنفاق المفتاح بالدولار USD؛ 0 يعني دون حد؛ يمكن أن يكون null |
| `expires_at` | `string` | لا | ؛ وقت انتهاء الصلاحية بصيغة ISO 8601؛ يمكن أن يكون null |
| `reset_quota` | `boolean` | لا | ؛ إعادة تعيين الجزء المستخدم من حد الإنفاق؛ يمكن أن يكون null |
| `rate_limit_5h` | `number` | لا | ؛ يمكن أن يكون null |
| `rate_limit_1d` | `number` | لا | ؛ يمكن أن يكون null |
| `rate_limit_7d` | `number` | لا | ؛ يمكن أن يكون null |
| `reset_rate_limit_usage` | `boolean` | لا | ؛ إعادة تعيين الإنفاق المحتسب ضمن حدود النوافذ الزمنية؛ يمكن أن يكون null |

قالب جسم الطلب

```json
{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}
```

يشير PLACEHOLDER إلى مدخلاتك ونوعها. استبدل القيم وأبقِ الحقول الاختيارية المطلوبة فقط؛ لا ترسل العلامات النصية بدلاً من الأرقام أوboolean أوالكائنات أوالمصفوفات.

مخطط الطلب: `UpdateAPIKeyRequest`

## الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: `APIKey`. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}
```

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: تغيّر العملية الحالة أو تواصل مصادقة لمرة واحدة؛ يصف المثال العقد ولا يتم تنفيذه.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

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

تغيّر الطريقة البيانات. تكون إعادة الإرسال آمنة فقط إذا ذُكر Idempotency-Key لهذه الطريقة. إذا فُقد الرد، فتحقق أولاً من النتيجة (مثل قائمة المفاتيح)، ثم قرر ما إذا كنت ستعيد الطلب.

هل لديك أسئلة أخرى؟ أرسل Request ID ووصفاً للمشكلة وسنساعدك على فهمها.[مراسلة الدعم](mailto:support@ailoot.ai)

## Ailoot · الشركة ومحفظة مشاريعها





تستند Ailoot إلى خبرة تشغيلية متراكمة وقاعدة عملاء واسعة وخدمة مستقرة ومراقبة مستمرة لمؤشرات الأداء KPI.





الشركة ومحفظة مشاريعها: ملايين العملاء؛ مبيعات بالمليارات شهريًا.





توظف Ailoot هذه الخبرة التشغيلية لإتاحة الوصول عبر API إلى قدرات الذكاء الاصطناعي في منتجات العملاء ووكلائهم وتطبيقاتهم وعمليات الأتمتة.