احراز هویت و کلیدها
هر درخواست به /v1 و /mcp باید کلید API شما را در سرآیند Authorization: Bearer یا X-API-Key داشته باشد. کلید را در پنل می‌سازید، می‌چرخانید و باطل می‌کنید.
کلید را چطور بفرستم؟
Section titled “کلید را چطور بفرستم؟”کلید را در یکی از این دو سرآیند بفرستید. روش پیشنهادی Authorization است و همهٔ نمونه‌های این مستندات از آن استفاده می‌کنند.
Authorization: Bearer rosha_xxxxxxxx_your-secretX-API-Key: rosha_xxxxxxxx_your-secretنمونهٔ کامل:
curl "https://poolick.ir/v1/instruments?q=IRO1FOLD0001" \ -H "Authorization: Bearer $ROSHA_KEY"همین کلید و همین سرآیندها برای سرور MCP در https://poolick.ir/mcp هم به کار می‌رود.
کلید چه شکلی دارد؟
Section titled “کلید چه شکلی دارد؟”کلید روشا سه بخش دارد: rosha_<8 hex>_<secret>.
- دو بخش اول، مثل
rosha_xxxxxxxx، پیشوند کلید است. پیشوند محرمانه نیست و در پنل دیده می‌شود. در گفت‌وگو با پشتیبانی فقط پیشوند را بفرستید. - بخش سوم محرمانه است. روشا فقط SHA-256 کلید را نگه می‌دارد؛ پس کلید گم‌شده قابل بازیابی نیست.
کلیدهایی که پیش‌تر با پیشوند tse_ صادر شده‌اند همچنان معتبرند و نیازی به تعویض ندارند.
چرخهٔ عمر کلید چیست؟
Section titled “چرخهٔ عمر کلید چیست؟”کلید یک بار نمایش داده می‌شود، تا وقتی باطل یا منقضی نشده کار می‌کند، و هر تغییر آن حداکثر ظرف ۶۰ ثانیه اعمال می‌شود.
| مرحله | چه می‌شود | کجا |
|---|---|---|
| صدور | با ثبت‌نام، اولین کلید ساخته و یک بار نمایش داده می‌شود. کلیدهای بعدی را خودتان می‌سازید. | پنل |
| تعداد | هر پلن سقف تعداد کلید دارد (تا آبان ۱۴۰۵: رایگان ۱، پایه ۲، حرفه‌ای ۳). | محدودیت‌ها و پلن‌ها |
| چرخش (rotate) | کلید فعلی باطل می‌شود و کلید تازه‌ای با همان نام نمایش داده می‌شود. | پنل |
| ابطال (revoke) | کلید از کار می‌افتد. درخواست با آن 401 key_revoked می‌گیرد. |
پنل |
| انقضا | کلید می‌تواند تاریخ انقضا داشته باشد. پس از آن 401 key_expired می‌گیرد. |
پنل |
چرخش و ابطال معمولاً بلافاصله اثر می‌کند و در بدترین حالت ۶۰ ثانیه طول می‌کشد. چون چرخش کلید قبلی را همان لحظه باطل می‌کند، کلید تازه را بی‌درنگ در محیط اجرای خود جایگزین کنید.
چطور کلید را امن نگه دارم؟
Section titled “چطور کلید را امن نگه دارم؟”کلید را مثل گذرواژه نگه دارید: فقط روی سرور، فقط در متغیر محیطی یا secret manager.
- کلید را در کد سمت مرورگر یا اپلیکیشن موبایل نگذارید. هر کاربری می‌تواند آن را ببیند. درخواست‌ها را از سرور خودتان بفرستید.
- کلید را در مخزن کد commit نکنید. آن را از
ROSHA_KEYبخوانید. - اگر پلن شما چند کلید می‌دهد، برای هر محیط یا سامانه کلید جدا بسازید تا در صورت نیاز فقط همان یکی را باطل کنید.
- اگر احتمال می‌دهید کلید فاش شده است، همان لحظه در پنل آن را بچرخانید.
- در تیکت پشتیبانی فقط پیشوند کلید را بنویسید، هرگز کلید کامل را.
اگر احراز هویت رد شد چه کنم؟
Section titled “اگر احراز هویت رد شد چه کنم؟”پاسخ رد همیشه JSON با دو فیلد detail و code است و پاسخ‌های 401 سرآیند WWW-Authenticate: Bearer هم دارند. در کد خود بر اساس code تصمیم بگیرید.
{"detail": "API key is not valid.", "code": "invalid_key"}جدول کامل کدها و راه رفع هر کدام در خطاها است.
صفحهٔ اصلی · قیمت‌ها · وضعیت · پنل · پشتیبانی
داده‌ها توصیهٔ سرمایه‌گذاری نیست. سلب مسئولیت