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

> کلید API روشا را در سرآیند Authorization یا X-API-Key بفرستید؛ چرخهٔ عمر کلید، چرخش، ابطال و نکته‌های نگهداری امن آن.
> Source: https://poolick.ir/docs/authentication/

هر درخواست به `/v1` و `/mcp` باید کلید API شما را در سرآیند `Authorization: Bearer` یا `X-API-Key` داشته باشد. کلید را در [پنل](/panel/) می‌سازید، می‌چرخانید و باطل می‌کنید.

## کلید را چطور بفرستم؟

کلید را در یکی از این دو سرآیند بفرستید. روش پیشنهادی `Authorization` است و همهٔ نمونه‌های این مستندات از آن استفاده می‌کنند.

```
Authorization: Bearer rosha_xxxxxxxx_your-secret
X-API-Key: rosha_xxxxxxxx_your-secret
```

نمونهٔ کامل:

```bash
curl "https://poolick.ir/v1/instruments?q=IRO1FOLD0001" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

همین کلید و همین سرآیندها برای سرور MCP در `https://poolick.ir/mcp` هم به کار می‌رود.

:::caution
کلید در query string پذیرفته نمی‌شود، چون نشانی‌ها در لاگ سرورها و پراکسی‌ها می‌مانند. نشانی‌ای مثل `?api_key=...` خطای `401 key_required` می‌گیرد.
:::

## کلید چه شکلی دارد؟

کلید روشا سه بخش دارد: `rosha_<8 hex>_<secret>`.

- دو بخش اول، مثل `rosha_xxxxxxxx`، **پیشوند** کلید است. پیشوند محرمانه نیست و در پنل دیده می‌شود. در گفت‌وگو با پشتیبانی فقط پیشوند را بفرستید.
- بخش سوم محرمانه است. روشا فقط SHA-256 کلید را نگه می‌دارد؛ پس کلید گم‌شده قابل بازیابی نیست.

کلیدهایی که پیش‌تر با پیشوند `tse_` صادر شده‌اند همچنان معتبرند و نیازی به تعویض ندارند.

## چرخهٔ عمر کلید چیست؟

کلید یک بار نمایش داده می‌شود، تا وقتی باطل یا منقضی نشده کار می‌کند، و هر تغییر آن حداکثر ظرف ۶۰ ثانیه اعمال می‌شود.

| مرحله | چه می‌شود | کجا |
|---|---|---|
| صدور | با ثبت‌نام، اولین کلید ساخته و یک بار نمایش داده می‌شود. کلیدهای بعدی را خودتان می‌سازید. | [پنل](/panel/) |
| تعداد | هر پلن سقف تعداد کلید دارد (تا آبان ۱۴۰۵: رایگان ۱، پایه ۲، حرفه‌ای ۳). | [محدودیت‌ها و پلن‌ها](/docs/limits/) |
| چرخش (rotate) | کلید فعلی باطل می‌شود و کلید تازه‌ای با همان نام نمایش داده می‌شود. | پنل |
| ابطال (revoke) | کلید از کار می‌افتد. درخواست با آن `401 key_revoked` می‌گیرد. | پنل |
| انقضا | کلید می‌تواند تاریخ انقضا داشته باشد. پس از آن `401 key_expired` می‌گیرد. | پنل |

چرخش و ابطال معمولاً بلافاصله اثر می‌کند و در بدترین حالت ۶۰ ثانیه طول می‌کشد. چون چرخش کلید قبلی را همان لحظه باطل می‌کند، کلید تازه را بی‌درنگ در محیط اجرای خود جایگزین کنید.

## چطور کلید را امن نگه دارم؟

کلید را مثل گذرواژه نگه دارید: فقط روی سرور، فقط در متغیر محیطی یا secret manager.

- کلید را در کد سمت مرورگر یا اپلیکیشن موبایل نگذارید. هر کاربری می‌تواند آن را ببیند. درخواست‌ها را از سرور خودتان بفرستید.
- کلید را در مخزن کد commit نکنید. آن را از `ROSHA_KEY` بخوانید.
- اگر پلن شما چند کلید می‌دهد، برای هر محیط یا سامانه کلید جدا بسازید تا در صورت نیاز فقط همان یکی را باطل کنید.
- اگر احتمال می‌دهید کلید فاش شده است، همان لحظه در پنل آن را بچرخانید.
- در تیکت پشتیبانی فقط پیشوند کلید را بنویسید، هرگز کلید کامل را.

## اگر احراز هویت رد شد چه کنم؟

پاسخ رد همیشه JSON با دو فیلد `detail` و `code` است و پاسخ‌های `401` سرآیند `WWW-Authenticate: Bearer` هم دارند. در کد خود بر اساس `code` تصمیم بگیرید.

```json
{"detail": "API key is not valid.", "code": "invalid_key"}
```

جدول کامل کدها و راه رفع هر کدام در [خطاها](/docs/errors/) است.