# حساب و کلید API

> ساخت حساب، شارژ اعتبار، ساخت کلید و فرستادن آن با هر درخواست

URL: https://dana.expert/docs/authentication

هر درخواست به API دانا باید یک کلید معتبر همراه داشته باشد. کلید به حساب شما وصل است و هزینهٔ درخواست‌ها از اعتبار همین حساب کم می‌شود.

## حساب

1. در [کنسول دانا](https://console.dana.expert) وارد شوید. ورود با شمارهٔ موبایل یا ایمیل است؛ اگر حساب ندارید، با رمز یک‌بارمصرف ساخته می‌شود.
2. از [بخش اعتبار](https://console.dana.expert/credit) حساب را با درگاه پرداخت ایرانی شارژ کنید.
3. در [بخش کلیدها](https://console.dana.expert/keys) کلید بسازید.

مصرف و موجودی را در [گزارش مصرف](https://console.dana.expert/usage) ببینید. قیمت هر مدل در [قیمت و توکن](https://dana.expert/docs/pricing-and-tokens) آمده است. برای پرسش دربارهٔ حساب به [info@dana.expert](mailto:info@dana.expert) بنویسید.

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

راه اصلی، هدر `Authorization` است:

```
Authorization: Bearer $DANA_API_KEY
```

```bash
curl https://api.dana.expert/v1/translate \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello"}'
```

هدر `x-api-key` هم پذیرفته می‌شود و همان کلید را می‌گیرد. SDK رسمی Anthropic به‌طور پیش‌فرض همین را می‌فرستد، پس روی رابط [Messages](https://dana.expert/docs/messages) کاری لازم نیست بکنید. اگر هر دو هدر را بفرستید، `Authorization` مقدم است.

## انواع کلید

| پیشوند | محیط | کاربرد |
|---|---|---|
| `dn-live-` | live | درخواست‌های واقعی، کسر اعتبار |
| `dn-test-` | test | تست، بدون کسر اعتبار |

کلیدهای test برای توسعه و تست‌اند و کلیدهای live برای پروداکشن.

## مدیریت کلید

کلیدها را در [کنسول دانا](https://console.dana.expert/keys) بسازید، نام بگذارید و باطل کنید.

سه نکتهٔ عملی:

- هر کلید یک بار به‌صورت کامل نمایش داده می‌شود. بعد از بستن پنجره ساخت، دیگر قابل بازیابی نیست و باید کلید تازه بسازید.
- کلید باطل‌شده تا حدود ۳۰ ثانیه ممکن است هنوز کار کند، چون نتیجه احراز هویت کوتاه‌مدت کش می‌شود. برای قطع فوری، کلید سرویس را هم عوض کنید.
- سقف نرخ روی خودِ کلید تنظیم می‌شود، نه روی حساب. پیش‌فرض ۶۰ درخواست در دقیقه است و شرحش در [محدودیت‌ها](https://dana.expert/docs/rate-limits) آمده.

## نگهداری امن

- کلید را در متغیر محیطی یا secrets manager بگذارید، نه داخل کد و نه در ریپوی گیت.
- برای هر سرویس و هر محیط یک کلید جدا بسازید. آن‌وقت باطل کردن یکی، بقیه را نمی‌خواباند.
- کلید را در مرورگر یا اپ موبایل نگذارید. هر چه به دست کاربر برسد، لو رفته است؛ درخواست را از سرور خودتان بفرستید.
- به کلید مشکوک شدید؟ اول در کنسول باطلش کنید، بعد دنبال علت بگردید.

## وقتی احراز هویت رد می‌شود

| کد | پیام | علت |
|---|---|---|
| `401` | `Missing API key.` | هیچ‌کدام از دو هدر ارسال نشده |
| `401` | `Invalid API key.` | کلید شناخته نشد، باطل شده یا ناقص کپی شده |
| `403` | - | کلید معتبر است ولی اجازه این مسیر را ندارد |

مطمئنید کلید درست است و باز `401` می‌گیرید؟ معمولا یکی از این سه است:

- کلمه `Bearer` جا افتاده.
- متغیر محیطی خالی مانده.
- موقع کپی، یک خط جدید یا فاصله هم آمده.

شرح کامل هر کد در [خطاها](https://dana.expert/docs/errors) آمده است.