احراز هویت و امنیت کلید
احراز هویت و امنیت کلید
هر درخواست به API دات‌هوش با یک API key احراز هویت می‌شود. این صفحه می‌گوید کلید را چطور بفرستید، چه شکلی دارد، چه چرخهٔ عمری دارد و چه خطاهایی به آن مربوط است.
سرآیند بستگی به پروتکل دارد
پرتکرارترین اشتباه در همین جدول خلاصه می‌شود: هر مسیر فقط یکی از دو سرآیند را می‌پذیرد.
| چه چیزی صدا می‌زنید | بفرستید | این را نفرستید |
|---|---|---|
| /v1/* (سازگار با OpenAI) | Authorization: Bearer dh_live_… | x-api-key |
| /anthropic/v1/messages | x-api-key: dh_live_… | Authorization |
اگر هر دو سرآیند را با هم بفرستید، یا سرآیند اشتباه را بفرستید، پاسخ api_key_malformed است؛ دات‌هوش حدس نمی‌زند منظورتان کدام بوده. روی مسیرهای OpenAI مقدار سرآیند باید دقیقاً Bearer به‌دنبال آن کلید باشد، بدون فاصلهٔ اضافه. روی مسیرهای Anthropic هم فرستادن Authorization پذیرفته نمی‌شود، حتی اگر کلید درست باشد.
مقدار هر دو سرآیند حساس است و هرگز در لاگ یا تلمتری نوشته نمی‌شود.
شکل کلید
| بخش | مقدار |
|---|---|
| پیشوند محیط production | dh_live_ |
| پیشوند محیط development | dh_test_ |
| طول secret در زمان ساخت | ۴۸ کاراکتر |
| بازهٔ پذیرفته‌شدهٔ secret | ۳۲ تا ۱۲۸ کاراکتر |
| کاراکترهای مجاز | حرف انگلیسی و رقم (A-Za-z0-9) |
کلیدی که این شکل را نداشته باشد، پیش از هر جست‌وجویی با api_key_malformed رد می‌شود؛ یعنی کلید بی‌شکل هرگز به سرویس سیاست نمی‌رسد. پذیرش شکل، شکل‌زدایی است نه اجازه: احراز هویت واقعی با تطبیق کلید روی سرویس سیاست انجام می‌شود.
چرخهٔ عمر کلید
- ساخته می‌شود در کنسول، مقید به یک پروژه و یک محیط. مقدار secret فقط یک بار نمایش داده می‌شود؛ در سرور فقط digest فلفل‌خورده ذخیره می‌شود و مقایسه در زمان ثابت انجام می‌گیرد.
- لغو می‌شود به درخواست شما. انتشار لغو چند ثانیه‌ای است (سقف DOTHOOSH_POLICY_CACHE_TTL_SECONDS، پیش‌فرض ۵ ثانیه)؛ پس از آن هر فراخوانی با api_key_revoked رد می‌شود.
- دور می‌خورد با یک بازهٔ هم‌پوشانی: پیش از بازنشستگی کلید قبلی، کلید تازه را منتشر می‌کنید. در بازهٔ هم‌پوشانی هر دو کار می‌کنند؛ بعد از آن کلید بازنشسته api_key_expired می‌دهد.
- به‌طور خودکار تعلیق می‌شود اگر نشانهٔ افشا داشته باشد: api_key_leak_suspended.
کنترل‌های زمان ساخت، در همان لحظه روی کلید نوشته می‌شوند: فهرست مدل‌های مجاز، فهرست IP مجاز، scopeها، زمان انقضا و سقف‌های مصرف (محدودیت‌ها).
نگهداری کلید
با کلید دات‌هوش مثل کلید خود ارائه‌دهنده رفتار کنید.
- آن را در متغیر محیطی یا secret manager بگذارید، نه در مخزن کد.
- هرگز آن را در بستهٔ مرورگر، اپ موبایل یا هر جایی که کاربر بتواند بخواند نگذارید. کلید bearer است: هر که آن را داشته باشد تا سقف همان key از کیف پول شما خرج می‌کند.
- برای هر استقرار یک کلید جدا بسازید. سقف‌ها و مصرف هر کلید فقط وقتی معنا دارند که کلیدها مشترک نباشند؛ لغو یک کلید مشترک، همه‌چیز را با هم از کار می‌اندازد.
- در محیط‌های غیرتولیدی از کلید dh_test_ استفاده کنید تا خطا محدود بماند.
اگر کلیدی لو رفت، اول لغو کنید و بعد بررسی. لغو فوری و بی‌هزینه است؛ ساخت جانشین چند ثانیه طول می‌کشد.
خطاهای احراز هویت و مجوز
| کد | HTTP | معنا |
|---|---|---|
| api_key_malformed | 401 | سرآیند اشتباه، هر دو سرآیند با هم، یا مقداری که شکل کلید را ندارد |
| api_key_invalid | 401 | شکل درست، اما کلید ناشناخته |
| api_key_revoked | 401 | کلید لغو شده است |
| api_key_disabled | 401 | کلید غیرفعال شده است |
| api_key_expired | 401 | از انقضای کلید گذشته، یا کلید چرخیده از بازهٔ هم‌پوشانی بیرون است |
| api_key_model_not_allowed | 403 | این کلید اجازهٔ صدا زدن این مدل را ندارد |
| api_key_environment_mismatch | 403 | محیط کلید با درخواست نمی‌خواند |
| api_key_ip_not_allowed | 403 | نشانی فراخوان بیرون از فهرست IP مجاز کلید است |
| api_key_scope_insufficient | 403 | کلید scope لازم برای این عملیات را ندارد |
| api_key_leak_suspended | 403 | کلید به‌دلیل نشانهٔ افشا معلق شده است |
| api_key_or_account_spend_limit | 403 | سقف هزینهٔ کلید یا حساب پر شده است |
| project_or_account_disabled | 403 | پروژه یا حساب مالک کلید غیرفعال است |
همهٔ این‌ها در سمت سرور و روی یک snapshot امضاشده از سیاست اجرا می‌شوند؛ هیچ‌کدام توصیه‌ای نیستند و از سمت کلاینت قابل شل‌کردن نیستند.
مطالب مرتبط
- اولین درخواست
- محدودیت‌ها — سقف‌هایی که همراه کلید ساخته می‌شوند
- خطاها و محدودیت‌ها — معنای retryable و قاعدهٔ تلاش دوباره
گام بعدی
این صفحه دقیقاً یک کار می‌کند: شما را از «کلید دارم» به «پاسخ گرفته‌ام» می‌رساند. پیش از این صفحه باید یک API key داشته باشید؛ اگر ندارید از احراز هویت و امنیت کلید شروع کنید.
دات‌هوش روی /v1/* همان قرارداد OpenAI را می‌پذیرد: همان مسیرها، همان سرآیندها و همان شکل پاسخ. برای مهاجرت، فقط آدرس پایه و کلید را عوض کنید.
دات‌هوش مسیر بومی Anthropic Messages را هم ارائه می‌دهد: POST /anthropic/v1/messages با همان قالب درخواست، همان رویدادهای استریم و همان پوشش خطا. SDK رسمی Anthropic و ابزارهایی که روی آن ساخته شده‌اند فقط به تغییر آدرس پایه و کلید نیاز دارند.