رفتن به محتوا

احراز هویت

نحوه استفاده از API Key برای احراز هویت درخواست‌ها

مستندات

دریافت API Token

هیبانا نشست (session) و لاگین ندارد: هر درخواست با یک کلید API شناسایی می‌شود که در داشبورد می‌سازید. یک‌بار بسازید، در متغیر محیطی نگه دارید، و در هدر هر درخواست بفرستید.

  1. وارد داشبورد خود شوید
  2. به بخش "کلیدهای API" بروید
  3. یک کلید جدید ایجاد کنید
  4. توکن را با احتیاط کپی کنید (دوباره نمایش داده نخواهد شد)

راهنمای تصویری همین مراحل در دریافت کلید API آمده است.

استفاده از API Token

توکن را در هدر Authorization قرار دهید:

Authorization: Bearer YOUR_API_TOKEN

توکن یک رشته‌ی JWT منفرد است که در داشبورد برای شما تولید می‌شود

اگر از SDK رسمی OpenAI استفاده می‌کنید، این هدر را خودِ کتابخانه می‌سازد؛ کافی است کلید را به api_key بدهید. نمونهٔ کامل در شروع سریع هست.

هدرهای هر درخواست

هدرهای الزامی
هدرمقدارتوضیح
AuthorizationBearer YOUR_API_KEYالزامی برای هر endpoint. کلمهٔ Bearer، یک فاصله، سپس کلید.
Content-Typeapplication/jsonالزامی برای هر درخواستی که بدنهٔ JSON دارد (مثل chat/completions).

سه اشتباه زیر تقریباً همهٔ خطاهای 401 را می‌سازند:

# درستAuthorization: Bearer YOUR_API_KEY # غلط (کلمهٔ Bearer جا افتاده Authorization: YOUR_API_KEY # غلط) علامت نقل‌قول جزئی از مقدار هدر می‌شودAuthorization: "Bearer YOUR_API_KEY" # غلط، دو نقطه یا فاصله جا افتادهAuthorization Bearer YOUR_API_KEY

نمونه با cURL

curl --location 'https://api-ai.hibanacloud.ir/v1/chat/completions' \--header 'Authorization: Bearer YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{    "model": "gpt-5-nano",    "messages": [{"role": "user", "content": "Hello!"}]  }'

اگر این دستور پاسخ گرفت، کلید شما سالم است و مشکل جای دیگری است. این اولین کاری است که حل مشکلات پیشنهاد می‌کند.

نکات امنیتی

نکات امنیتی:

  • کلید API خود را مانند رمز عبور نگاه دارید.
  • هرگز کلید را در کد عمومی یا Git نگذارید.
  • کلیدهای API را به صورت منظم تغییر دهید.
  • درصورت فاش شدن، بلافاصله کلید را غیرفعال کنید.

محدودیت نرخ (Rate Limiting)

  • محدودیت نرخ درخواست برای هر کاربر و مدل اعمال می‌شود
  • کاهش موجودی حساب در زمان واقعی انجام می‌شود
  • درخواست‌های بدون کلید API معتبر خطای 401 برگردانده می‌کنند

هدرهای X-RateLimit-*، پاسخ 429 و استراتژی درست برای تلاش مجدد در محدودیت نرخ درخواست آمده‌اند. موجودی کیف پول را هم می‌توانید از طریق بررسی موجودی کاربر بخوانید.