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

هر درخواست به https://api.uttapen.ir/v1 باید یک کلید API داشته باشد. کلید به کاربر تو وصل است، از کیف پول همان کاربر خرج می‌کند و می‌تواند محدودیت‌های خودش را داشته باشد. این صفحه همه‌چیز دربارهٔ ساخت، ارسال و مدیریت کلیدهاست.

فرمت کلید

کلید با sk-up- شروع می‌شود و بعد از آن ۴۰ کاراکتر تصادفی می‌آید. پیشوند sk- عمداً حفظ شده تا ابزارهایی که شکل کلید OpenAI را چک می‌کنند (بعضی افزونه‌ها و SDKهای غیررسمی) نشکنند. کلید کامل فقط یک بار، هنگام ساخت، نمایش داده می‌شود؛ ما فقط hash آن را نگه می‌داریم و بعداً فقط پیشوند و چهار کاراکتر آخر را در داشبورد می‌بینی.

ارسال کلید

دو شکل پذیرفته می‌شود و هر دو معادل‌اند:

Authorization: Bearer sk-up-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

X-API-Key: sk-up-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

SDKهای رسمی OpenAI شکل اول را خودشان می‌فرستند؛ فقط api_key را بده. X-API-Key برای ابزارهایی است که هدر Authorization را برای چیز دیگری اشغال کرده‌اند. اگر هر دو را بفرستی، Authorization ملاک است.

بدون کلید یا با کلید نامعتبر، پاسخ 401 با کد invalid_api_key است:

{"error":{"message":"کلید API نامعتبر، لغوشده یا منقضی است.","type":"invalid_api_key","code":"invalid_api_key","param":null}}

تنها مسیرهایی که بدون کلید کار می‌کنند GET /v1/models، GET /v1/models/{id} و GET /healthz هستند.

تنظیمات هر کلید

از داشبورد ← کلیدها برای هر کلید این‌ها را می‌توانی ست کنی. همه اختیاری‌اند و بعد از ساخت هم قابل تغییرند.

برای کلید سرور اصلی سقف ماهانه بگذار و برای کلیدی که به یک اسکریپت یا همکار می‌دهی، allowed_models را به یکی دو مدل ارزان محدود کن. این کار جلوی هزینهٔ ناخواسته را می‌گیرد بدون این که کیف پول جدا لازم باشد.

لغو کلید

لغو از داشبورد فوری است: کش gateway همان لحظه پاک می‌شود و درخواست بعدی با آن کلید 401 می‌گیرد، حتی اگر یک ثانیه بعد از لغو باشد. استریم‌هایی که قبل از لغو شروع شده‌اند تا پایان ادامه می‌یابند و هزینه‌شان طبق معمول ثبت می‌شود. کلید لغوشده برنمی‌گردد؛ کلید تازه بساز.

وضعیت کلید و حساب

GET /v1/uttapen/me با همان کلید، وضعیت کلید و کیف پول را برمی‌گرداند. برای چک کردن اتصال قبل از استقرار مفید است.

curl https://api.uttapen.ir/v1/uttapen/me \
  -H "Authorization: Bearer $UTTAPEN_API_KEY"

{
  "user": {"id": "01900000-0000-7000-8000-000000000001", "phone_masked": "0912***0001"},
  "key": {
    "name": "local-dev",
    "prefix": "sk-up-62nBtYlq",
    "monthly_limit_toman": null,
    "spent_this_month_toman": "2402.551503",
    "rate_limit_rpm": 60,
    "allowed_models": null
  },
  "wallet": {
    "balance_toman": "97571.073497",
    "held_toman": "0.000000",
    "available_toman": "97571.073497"
  },
  "prices_updated_at": "2026-09-06T22:19:22Z"
}

همهٔ مبالغ رشته هستند تا دقت اعشاری از دست نرود؛ در JavaScript آن‌ها را به Number تبدیل نکن، از decimal.js یا نمایش مستقیم استفاده کن. available_toman همان balance_toman منهای held_toman است و عددی است که برای قبول درخواست بعدی ملاک قرار می‌گیرد. prices_updated_at آخرین زمان به‌روزرسانی قیمت مدل‌هاست.

نکات امنیتی

• کلید را در کد، ریپو یا کلاینت (مرورگر، اپ موبایل) نگذار. از متغیر محیطی یا secret manager بخوان. اگر در commit رفت، همان لحظه لغوش کن.
• برای مرورگر و موبایل، درخواست را از سرور خودت به یوتاپن بفرست. نمونهٔ proxy در استریم هست.
• برای هر محیط (توسعه، staging، production) کلید جدا بساز و نام‌گذاری کن تا در گزارش مصرف با group_by=key تفکیک شوند.
• برای کلیدهای موقت expires_at بگذار؛ پاک کردن کلید از ذهن آدم‌ها می‌رود، از سرور نه.
• gateway محتوای درخواست‌های API را ذخیره نمی‌کند (حریم خصوصی)، ولی کلیدِ لو رفته می‌تواند کیف پولت را خالی کند. سقف ماهانه ارزان‌ترین بیمه است.