احراز هویت

همه درخواست‌ها به APIهای Felo API Platform با یک کلید API احراز هویت می‌شوند. این راهنما توضیح می‌دهد چگونه درخواست‌های خود را احراز هویت کنید و مشکلات رایج احراز هویت را حل کنید.

احراز هویت با کلید API

Felo برای همه endpointهای v2 از احراز هویت با کلید API استفاده می‌کند. کلید API شما برنامه‌تان را شناسایی می‌کند و دسترسی به توانمندی‌های پلتفرم را فراهم می‌کند.

نحوه کار

1. یک کلید API از صفحه API Keys در Felo API Platform دریافت می‌کنید
2. کلید API را در سرآیند Authorization هر درخواست API می‌گنجانید
3. پلتفرم کلید API شما را اعتبارسنجی و درخواست را پردازش می‌کند

قالب سرآیند

کلید API خود را با طرح احراز هویت Bearer در سرآیند Authorization بگنجانید:

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 Keys در 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 (Command Prompt):

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 Keys لغو نشده است.
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!")

محدودیت نرخ

محدودیت‌های نرخ برای هر endpoint اعمال می‌شوند، نه به‌صورت سراسری برای هر کلید API. در حال حاضر فقط `/v2/chat` آن‌ها را اعمال می‌کند؛ کاربران با اشتراک مؤثر پولی Felo از آن معاف‌اند. دیگر endpointهای /v2/** محدودیت نرخ اعمال‌شده ندارند.

پاسخ 429 سرآیندهای X-RateLimit-* و Retry-After را شامل می‌شود. همیشه محدودیت‌های مؤثر را از سرآیندهای پاسخ بخوانید، نه از مستندات.

برای ابعاد کامل محدودیت نرخ، سرآیندها و سیاست تلاش دوباره، خطاها، محدودیت‌ها و تلاش دوباره را ببینید.

به کمک نیاز دارید؟

اگر با مشکل احراز هویت روبه‌رو هستید:

1. این راهنما را با دقت مرور کنید
2. راهنمای شروع به کار را ببینید
3. کلید API خود را در صفحه API Keys بررسی کنید
4. با شناسه درخواست خود با [email protected] تماس بگیرید

گام‌های بعدی

• راهنمای شروع به کار - بیاموزید نخستین فراخوانی API را چگونه انجام دهید
• مرجع Chat API - مستندات Chat API را کاوش کنید