المصادقة

تتطلب جميع الطلبات إلى واجهات Felo API Platform المصادقة باستخدام مفتاح API. يشرح هذا الدليل كيفية مصادقة طلباتك ومعالجة مشكلات المصادقة الشائعة.

مصادقة مفتاح API

يستخدم Felo مصادقة مفتاح API لجميع endpoints الإصدار v2. يحدد مفتاح API تطبيقك ويتيح الوصول إلى قدرات المنصة.

كيف يعمل

1. تحصل على مفتاح API من صفحة مفاتيح API في Felo API Platform
2. تضمّن مفتاح API في رأس Authorization في كل طلب API
3. تتحقق المنصة من مفتاح API لديك وتعالج طلبك

تنسيق الرأس

ضمّن مفتاح API في رأس Authorization باستخدام مخطط مصادقة Bearer:

Authorization: Bearer YOUR_API_KEY

مثال على طلب

curl -X POST https://openapi.felo.ai/v2/chat \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?"}'

الحصول على مفتاح API

للحصول على مفتاح API:

1. افتح صفحة مفاتيح API في Felo API Platform
2. سجّل الدخول بحساب Felo إذا طُلب منك ذلك
3. أدخل اسمًا للمفتاح وانقر على Create Key
4. انسخ المفتاح الكامل عند ظهوره. لا يُعرض إلا مرة واحدة
5. خزّن المفتاح بأمان واستخدمه باسم FELO_API_KEY

أفضل ممارسات الأمان

1. خزّن مفاتيح API بأمان

لا تضع مفاتيح API مباشرة في شيفرة المصدر:

# ❌ Bad - API Key exposed in code
api_key = "sk_live_abc123xyz789"

افعل التالي: استخدم متغيرات بيئة أو إعدادًا آمنًا:

# ✅ Good - API Key from environment
import os
api_key = os.environ.get('FELO_API_KEY')

2. استخدم متغيرات البيئة

خزّن مفتاح API في متغيرات البيئة:

Linux/macOS:

export FELO_API_KEY="sk_live_abc123xyz789"

Windows (موجه الأوامر):

set FELO_API_KEY=sk_live_abc123xyz789

Windows (PowerShell):

$env:FELO_API_KEY="sk_live_abc123xyz789"

3. دوّر المفاتيح بانتظام

أنشئ مفاتيح API جديدة بشكل دوري وألغِ المفاتيح القديمة لتقليل المخاطر الأمنية إلى الحد الأدنى.

4. استخدم مفاتيح مختلفة لبيئات مختلفة

أنشئ مفاتيح API منفصلة لبيئات التطوير والاختبار والإنتاج.

5. لا تكشف المفاتيح أبدًا في شيفرة جانب العميل

ينبغي استخدام مفاتيح API في شيفرة جانب الخادم فقط. لا تضمّنها أبدًا في:

• شيفرة JavaScript للواجهة الأمامية
• شيفرة مصدر تطبيق الجوال
• مستودعات عامة
• ملفات إعداد جانب العميل

أخطاء المصادقة

للاطلاع على غلاف الأخطاء الكامل ورؤوس حد المعدل وسياسة إعادة المحاولة، راجع الأخطاء والحدود وإعادة المحاولة.

رموز الأخطاء الشائعة

يعيد الطلب المرفوض حالة المفتاح في message:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key is required",
  "request_id": "..."
}

status هو رمز حالة HTTP. يعيد المفتاح الملغى الرسالة API Key has been revoked (keyPrefix=...). اعتمد على حالة HTTP وcode، لا على الصياغة الدقيقة لـmessage.

استكشاف الأخطاء وإصلاحها

إذا فشلت المصادقة:

1. تحقق من أن الرأس هو بالضبط Authorization: Bearer YOUR_API_KEY.
2. تأكد من أن المفتاح لم يُلغَ في صفحة مفاتيح API.
3. تأكد من أن البيئة تستخدم المفتاح المتوقع.
4. أنشئ مفتاحًا جديدًا إذا حُذف المفتاح القديم أو دُوّر. لا يُعرض المفتاح الكامل إلا مرة واحدة عند الإنشاء.

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

مثال: تصحيح أخطاء المصادقة

import requests

url = "https://openapi.felo.ai/v2/chat"
api_key = "YOUR_API_KEY"

# Correct format
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={"query": "test"})

if response.status_code == 401:
    error = response.json()
    print(f"Authentication failed: {error['code']}")
    print(f"Message: {error['message']}")
    print(f"Request ID: {error['request_id']}")
else:
    print("Authentication successful!")

Rate Limiting (حدود المعدل)

تُفرض حدود المعدل لكل endpoint، وليس عالميًا لكل مفتاح API. حاليًا، لا يفرضها إلا `/v2/chat`؛ ويُستثنى المستخدمون الذين لديهم اشتراك Felo مدفوع ساري. لا توجد حدود معدل مفروضة على endpoints أخرى ضمن /v2/**.

تتضمن استجابة 429 رؤوس X-RateLimit-* وRetry-After. اقرأ الحدود الفعلية دائمًا من رؤوس الاستجابة، لا من التوثيق.

للاطلاع على أبعاد حد المعدل الكاملة والرؤوس وسياسة إعادة المحاولة، راجع الأخطاء والحدود وإعادة المحاولة.

هل تحتاج إلى مساعدة؟

إذا كنت تواجه مشكلات في المصادقة:

1. راجع هذا الدليل بعناية
2. راجع دليل البدء
3. تحقق من مفتاح API في صفحة مفاتيح API
4. تواصل مع الدعم على [email protected] مع معرّف الطلب

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

• دليل البدء - تعلّم كيفية إجراء أول استدعاء API
• مرجع Chat API - استكشف توثيق Chat API