راهنمای احراز هویت Claude API در AWS، Google و Azure
نحوه اتصال Claude API با استفاده از Anthropic key، AWS IAM، Google ADC یا Microsoft Entra را بیاموزید. این راهنما تنظیمات امن اعتبارنامه برای سرورهای لینوکسی را پوشش میدهد.
مسیرهای احراز هویت Claude API
احراز هویت Claude API به یک تصمیم نهایی ختم میشود: کلاینت شما چه نوع اعتباری (credential) را در شبکه ارسال میکند. Anthropic علاوه بر Claude API مستقیم، پنج پلتفرم ابری دیگر را نیز پشتیبانی میکند: Amazon Bedrock، پلتفرم Claude روی AWS، مدلهای Claude روی Google Cloud (مدیریتشده توسط گوگل)، مدلهای Claude روی Google Cloud (مدیریتشده توسط Anthropic) و Microsoft Foundry. در API مستقیم Anthropic، میتوانید از یک API key یا یک توکن کوتاهمدت در هدر Authorization: Bearer استفاده کنید؛ هدر قدیمی x-api-key نیز همچنان API key را میپذیرد. Amazon Bedrock از امضای درخواست AWS و Bedrock API keys پشتیبانی میکند و در این ساختار، هیچ کلید Anthropic وجود ندارد. Google Cloud یک توکن دسترسی کوتاهمدت گوگل ارسال میکند. Microsoft Foundry نیز یک کلید صادرشده توسط Azure یا یک توکن Microsoft Entra را میپذیرد. چهار بخش زیر این تنظیمات اعتبارنامه را پوشش میدهند و سرویسهای AWS و Google Cloud که توسط Anthropic مدیریت میشوند، در کنار همتایان ابری خود توضیح داده شدهاند.
این راهنما برای اتصال یک SDK (کیت توسعه نرمافزار) به سرویسی است که روی یک سرور لینوکسی اجرا میشود. اگر در حال پیکربندی ابزار خط فرمان Claude Code هستید، متغیرها و جریان کار متفاوت است: به اشاره Claude Code به Bedrock یا Vertex مراجعه کنید. اگر سرویس هنوز وجود ندارد، ابتدا آن را با اولین برنامه Claude API روی یک VPS بسازید و سپس برای دریافت اعتبارنامه به اینجا بازگردید.
تمام موارد زیر در اوت 2026 با مستندات پلتفرم Anthropic مطابقت داده شده و در 16 اکتبر 2026 مجدداً با مستندات هر ارائهدهنده بررسی شدند؛ جزئیات دسترسی به مدل Bedrock در 19 اکتبر 2026 با مستندات AWS بازبینی شد. صفحات Anthropic برای هر چهار مسیر، کلیدهای API و نسخههای API در 27 اکتبر 2026 دوباره بررسی شدند. صفحات Anthropic برای Microsoft Foundry، هر دو اندپوینت Bedrock، مسیر مدیریتشده توسط گوگل، پلتفرم Claude روی AWS، احراز هویت، Workload Identity Federation و نسخههای API در 10 نوامبر 2026 به همراه تغییرات (changelog) نسخه Ruby SDK بازبینی شدند. شناسههای مدل، قیمتها، نسخههای SDK و ساختار اندپوینتها همواره در حال تغییر هستند، بنابراین این راهنما به جای درج مقادیری که قدیمی میشوند، به صفحات ارائهدهندگان لینک میدهد.
مسیر 1: کلید API شرکت Anthropic
این مسیر مستقیمترین راه است و تنها روشی است که در آن Anthropic کلید محرمانه را صادر میکند. درخواستها به endpoint مربوط به Messages در میزبان API شرکت Anthropic ارسال میشوند و هر درخواست باید شامل سه هدر باشد.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "MODEL_ID", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'عبارت MODEL_ID را با یک شناسه فعلی از نمای کلی مدلهای Anthropic جایگزین کنید. پاسخ صحیح، یک JSON است که شامل یک آرایه content و یک شیء usage میباشد. کلید اشتباه یا منقضیشده، خطای HTTP 401 را به همراه authentication_error برمیگرداند. نبود هدر anthropic-version یک خطای مجزا محسوب میشود، زیرا این هدر در هر درخواست الزامی است؛ SDKها این هدر را بهطور خودکار برای شما تنظیم میکنند. تا اکتبر 2026، مستندات Anthropic از Authorization: Bearer بهعنوان روش اصلی ارسال کلید یاد کرده و x-api-key را قدیمی (legacy) مینامد، اما هر دو روش پذیرفته میشوند و دستور بالا همچنان کار میکند. نسخههای اصلی فعلی SDK نیز کلید را بهعنوان Authorization: Bearer ارسال میکنند، بنابراین اگر از proxy یا gateway استفاده میکنید که X-Api-Key را میخواند، هنگام ارتقای SDK باید آن را تغییر دهید. نسخه 2023-06-01 در دستور بالا همچنان پذیرفته میشود؛ جدیدترین نسخه API شرکت Anthropic، نسخه 2026-10-21 است که نسخههای جدید SDK بهصورت پیشفرض از آن استفاده میکنند و برخی پارامترهای قدیمی درخواست مانند temperature را نمیپذیرد.
ساخت کلاینت در این روش کوتاهترین مرحله است، زیرا چیزی برای ساختن وجود ندارد. تمام SDKهای رسمی، متغیر ANTHROPIC_API_KEY را بهطور خودکار از محیط (environment) میخوانند.
import os
from anthropic import Anthropic
client = Anthropic() # reads ANTHROPIC_API_KEY from the environment
message = client.messages.create(
model=os.environ["CLAUDE_MODEL"],
max_tokens=64,
messages=[{"role": "user", "content": "Hello"}],
)
print(message.usage)نگهداری شناسه مدل در محیط (environment) در کنار کلید، کار عاقلانهای است. نام مدلها طبق زمانبندیهایی که شما کنترلی روی آنها ندارید تغییر میکنند و بازنشر (redeploy) کد فقط برای تغییر یک رشته، کاری غیرضروری است.
کلیدها در Console ایجاد میشوند، جایی که شما زمان انقضا را در لحظه ایجاد تعیین میکنید: گزینههای پیشفرض 3 ساعت، 1 روز، 7 روز یا 30 روز، یک مدتزمان سفارشی، یا گزینه Never (هرگز) که تابع سیاست حداکثر انقضای سازمان شماست. زمان انقضا در لحظه ایجاد ثابت میشود و بعداً قابل تغییر نیست. Anthropic پیش از انقضای کلیدهای با عمر طولانی به سازنده کلید ایمیل میزند، اما کلیدهایی با عمر کوتاه بدون هیچ هشدار ایمیلی منقضی میشوند. کلید منقضیشده خطای 401 برمیگرداند و قابل فعالسازی مجدد نیست، بنابراین تنها راهحل، ایجاد یک کلید جدید است.
در API مستقیم، هیچ منطقهای (region) برای انتخاب وجود ندارد و صورتحساب مستقیماً برای سازمان Anthropic شما صادر میشود. Workspaces کلید را به یک پروژه خاص محدود میکنند که تمیزترین راه برای مشاهده هزینههای یک سرویس واحد است. هنگام ایجاد کلید برای یک سرور، آن را به Workspace مربوطه محدود کنید: کلیدهای شخصی یا حسابهای کاربری سرویس که به یک Workspace محدود نشدهاند، باید در هر درخواست هدر anthropic-workspace-id را ارسال کنند، در غیر این صورت API با خطای 400 و invalid_request_error پاسخ میدهد. برای یک سرویس، از کلید حساب کاربری سرویس (service account key) استفاده کنید، زیرا کلید شخصی با خروج فرد سازنده از سازمان، از کار میافتد. برای درک محاسبات پشت آن صورتحساب، به مقایسه قیمتگذاری API بر اساس توکن با اشتراک مراجعه کنید.
یک گزینه دیگر نیز در اینجا جای میگیرد، زیرا نیاز به کلید محرمانه ثابت را بهکلی حذف میکند. Workload Identity Federation به یک workload اجازه میدهد تا یک توکن OpenID Connect (OIDC) از یک ارائهدهنده هویت که به آن اعتماد دارید را با یک توکن کوتاهمدت Anthropic در POST /v1/oauth/token مبادله کند و SDK پیش از انقضای آن توکن، آن را بهطور خودکار تمدید میکند. در این حالت، هیچ رشته sk-ant-api... ساخته یا کپی نمیشود. این روش برای Kubernetes، GitHub Actions و ماشینهای مجازی ابری که از قبل دارای هویت پلتفرم هستند، مناسب است. یک VPS معمولی معمولاً چنین صادرکنندهای ندارد، بنابراین در آن محیط، استفاده از کلید API در یک فایل، راهکار منطقی است و باقی این راهنما نیز بر همین اساس پیش میرود.
مسیر 2: استفاده از اعتبارنامههای AWS در Amazon Bedrock
در Bedrock شما اصلاً نیازی به کلید Anthropic ندارید. با استفاده از اعتبارنامههای AWS، کیت توسعه نرمافزار (SDK) هر درخواست HTTP را با امضای AWS Signature Version 4 (SigV4) امضا میکند و AWS تصمیم میگیرد که آیا آن فراخوانکننده اجازه دارد مدل را اجرا کند یا خیر.
pip install -U "anthropic[bedrock]"
aws sts get-caller-identityaws sts get-caller-identity شماره حساب و ARN (نام منبع آمازون) مربوط به هویتی که اعتبارنامههای شما به آن اشاره دارد را چاپ میکند. هنگام استفاده از SigV4، پیش از هر کار دیگری این دستور را اجرا کنید. برای SigV4، کیت توسعه نرمافزار اعتبارنامههای سازنده (constructor)، اعتبارنامههای محیطی و زنجیره استاندارد اعتبارنامههای AWS را بررسی میکند؛ انتخاب منطقه (region) فرآیندی جداگانه است. در کلاینت AnthropicBedrock پایتون، اگر یک کلید API مربوط به Bedrock را به عنوان api_key یا از طریق AWS_BEARER_TOKEN_BEDROCK ارائه دهید، در صورتی که aws_access_key، aws_secret_key، aws_session_token یا aws_profile را نیز ارسال کنید، خطای ValueError صادر میشود. بدون آن آرگومانهای صریح، کلید بهجای زنجیره اعتبارنامههای AWS، احراز هویت از نوع bearer را انتخاب میکند. کلاینت TypeScript، کلید API مربوط به Bedrock را بر اعتبارنامههای صریح AWS مقدم میداند. دستور STS احراز هویت bearer را تست نمیکند.
آنچه در ساخت کلاینت تغییر میکند، کلاس و یک آرگومان است.
from anthropic import AnthropicBedrock
client = AnthropicBedrock(aws_region="us-east-1")AnthropicBedrock یکپارچهسازی InvokeModel در Bedrock را مدیریت میکند. تا اکتبر 2026، Anthropic همچنین Claude را در Amazon Bedrock مستند کرده است که یک نقطه پایانی (endpoint) برای Messages API در https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages برای مدلهای Claude Opus 4.7 و نسخههای بعد از آن است و از طریق کلاینت AnthropicBedrockMantle از همان بسته در دسترس است. این مورد از اعتبارنامههای AWS و توکنهای bearer مربوط به Bedrock پشتیبانی میکند؛ همانطور که در ادامه توضیح داده شده، الزامات دسترسی به مدل بین این دو نقطه پایانی متفاوت است.
ارتقا در آن خط pip install -U را زیر نظر داشته باشید. از تاریخ 27 اکتبر 2026، جدیدترین کیت توسعه نرمافزار بهطور پیشفرض نسخه API 2026-10-21 را ارسال میکند (از جمله از طریق Bedrock). Anthropic مستند کرده است که شناسههای مدل با نسخه ARN که برای Claude Opus 4.6 و نسخههای قدیمیتر فهرست شدهاند، از این نسخه در Bedrock پشتیبانی نمیکنند و ممکن است خطای 400 برگردانند. اگر سرویسی یکی از آن مدلها را فراخوانی میکند، کیت توسعه نرمافزار را روی نسخهای که امروز با آن کار میکند نگه دارید و آن را ثابت (pin) کنید، یا ابتدا سرویس را به مدل Claude 4.7 یا جدیدتر منتقل کنید.
در اینجا منطقه (region) دیگر یک پارامتر تزئینی نیست. نقاط پایانی Bedrock به ازای هر منطقه هستند، مدلهای Claude ارائهشده در مناطق مختلف متفاوتاند و منطقه بخشی از امضای SigV4 است؛ بنابراین امضایی که برای یک منطقه محاسبه شده باشد، توسط منطقه دیگر رد میشود. مقدار AWS_REGION را بهطور صریح در محیط سرویس تنظیم کنید، زیرا کیتهای توسعه نرمافزار در مورد رفتار پیشفرض هنگام حذف آن توافق ندارند. همانطور که در اکتبر 2026 مستند شده است، کلاینت AnthropicBedrock پایتون، AWS_REGION یا AWS_DEFAULT_REGION را میخواند، سپس منطقه نشست boto3 یا پروفایل AWS شما (شامل ~/.aws/config) را بررسی میکند و اگر هیچکدام یافت نشد، خطای ValueError را صادر میکند. کلاینت TypeScript مقدار AWS_REGION را میخواند، در صورت تنظیم نبودن به us-east-1 بازمیگردد و ~/.aws/config را برای منطقه نمیخواند. به همین دلیل است که AWS CLI میتواند مدلهای Claude را با موفقیت در همان سیستمی فهرست کند که یک پردازش Node منطقه اشتباهی را فراخوانی میکند: CLI فایل پیکربندی شما را خوانده است اما کلاینت این کار را نکرده است.
روی یک نمونه EC2، شما یک نقش IAM (مدیریت هویت و دسترسی) متصل میکنید و هیچ رمز عبوری روی دیسک ذخیره نمیشود، زیرا سرویس متادیتای نمونه، اعتبارنامههای موقت را به کیت توسعه نرمافزار تحویل میدهد. یک VPS خارج از AWS نه نقش نمونه دارد و نه سرویس متادیتا. در این صورت شما باید بین جفت کلید دسترسی بلندمدت یک کاربر IAM که روی سیستم ذخیره شده (که همان کلاس رمز عبور کلید Anthropic است) و فدراسیون یکی را انتخاب کنید: احراز هویت در برابر ارائهدهنده هویت خود، فراخوانی AWS STS (سرویس توکن امنیتی) و استفاده از اعتبارنامههای موقتی که برمیگرداند. Bedrock همچنین کلیدهای API مربوط به Bedrock را میپذیرد که توکنهای bearer هستند و از طریق AWS_BEARER_TOKEN_BEDROCK ارسال میشوند؛ AWS دو نوع از آنها را مستند کرده است. یک کلید کوتاهمدت حداکثر 12 ساعت یا به اندازه طول نشست ایجادکننده آن (هرکدام کوتاهتر باشد) اعتبار دارد، مجوزهای هویت IAM ایجادکننده خود را به ارث میبرد و نوعی است که AWS برای محیط تولید توصیه میکند. یک کلید بلندمدت تا زمان انقضایی که هنگام ایجاد انتخاب میکنید (مثلاً 30 یا 90 روز با --credential-age-days) اعتبار دارد، یا اگر آن پارامتر API حذف شود، منقضی نمیشود؛ کنسول در پشت صحنه یک کاربر IAM برای آن ایجاد میکند و AWS آن را فقط برای اکتشاف توصیه میکند. یک کلید بلندمدت فقط در منطقهای که ایجاد شده کار میکند؛ استفاده از آن در منطقه دیگر منجر به خطای Credential should be scoped to a valid region میشود.
هزینهها بهجای Anthropic، در حساب AWS شما ثبت میشود که معمولاً دلیل اصلی استفاده از این سرویس است. همانطور که در اکتبر 2026 مستند شده است، نقاط پایانی منطقهای 10 درصد گرانتر از نقطه پایانی جهانی هستند. Claude Platform در AWS یک محصول جداگانه است: Anthropic آن را اداره میکند، AWS از طریق AWS Marketplace صورتحساب آن را صادر میکند و با SigV4 یا کلید API ایجادشده در کنسول AWS (کلیدهای کنسول Claude در آنجا کار نمیکنند) از طریق کلاینت AnthropicAWS که Anthropic آن را به عنوان نسخه بتا علامتگذاری کرده، احراز هویت میشود. یک خطای Bedrock ارزش شناختن دارد زیرا شبیه به مشکل مجوز است اما نیست: Invocation of model ID ... with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model. این مورد مربوط به مسیریابی مدل است و هیچ تغییری در اعتبارنامهها آن را حل نخواهد کرد.
مسیر 3: اعتبارسنجی Google در Vertex AI
مستندات Anthropic اکنون این مسیر را Claude Models on Google Cloud (مدیریتشده توسط Google) مینامد که Google آن را به عنوان بخشی از Agent Platform اجرا میکند؛ نام جدیدی که Google برای آنچه از Vertex AI تکامل یافته، برگزیده است. میزبان aiplatform.googleapis.com، مقدار اضافی anthropic[vertex] و کلاس AnthropicVertex که در زیر نمایش داده شدهاند، بدون تغییر باقی ماندهاند.
Google Cloud از Application Default Credentials (ADC) استفاده میکند؛ یک ترتیب جستجوی ثابت که کتابخانههای احراز هویت Google برای یافتن اعتبارنامه بدون نیاز به نامگذاری دستی توسط شما، از آن پیروی میکنند. ADC ابتدا GOOGLE_APPLICATION_CREDENTIALS، سپس فایلی که توسط gcloud auth application-default login نوشته شده و در نهایت حساب سرویسی (service account) که از طریق سرور متادیتا متصل شده است را بررسی میکند.
pip install -U "anthropic[vertex]"
gcloud auth application-default loginروی یک ایستگاه کاری، آن ورود به سیستم، $HOME/.config/gcloud/application_default_credentials.json را مینویسد و کار شما تمام است. روی یک سرور، از ذخیره اعتبارنامههای یک کاربر انسانی اجتناب کنید؛ این دستور از جعل هویت حساب سرویس (service account impersonation) نیز پشتیبانی میکند. خارج از Google Cloud، سرور متادیتای Google وجود ندارد، بنابراین از GOOGLE_APPLICATION_CREDENTIALS برای اشاره ADC به یک فایل پیکربندی Workload Identity Federation یا یک فایل کلید حساب سرویس استفاده کنید. یک فایل JSON کلید حساب سرویس، یک راز با طول عمر زیاد است و دقیقاً به همان مدیریتی نیاز دارد که در ادامه این راهنما شرح داده شده است. داخل Google Cloud، یک حساب سرویس به VM متصل کنید تا دیگر فایلی برای محافظت وجود نداشته باشد. هر هویتی که ADC پیدا میکند، به یک نقش IAM نیاز دارد که شامل مجوز aiplatform.endpoints.predict باشد، مانند Agent Platform User (roles/aiplatform.user).
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")اگر از سطح SDK پایینتر بروید و از HTTP خام استفاده کنید، دو مورد تغییر میکند. شناسه مدل از بدنه درخواست خارج شده و به مسیر URL منتقل میشود و anthropic_version از هدر خارج شده و به بدنه میرود. از تاریخ 27 اکتبر 2026، مستندات Anthropic یا vertex-2023-10-16 و یا نسخه جدیدتر API یعنی 2026-10-21 را در آنجا میپذیرد. اعتبارنامه، یک توکن دسترسی معمولی Google است. در دستور زیر، gcloud auth print-access-token به جای ADC از ورود به سیستم خودِ gcloud CLI استفاده میکند، بنابراین ابتدا gcloud auth login یا gcloud init را روی ماشینی که آن را تست میکنید، اجرا کنید.
curl https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/anthropic/models/${MODEL_ID}:rawPredict \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'منطقه (Region) یک آرگومان درجه یک است. global مسیرها را به صورت پویا برای دسترسیپذیری هدایت میکند، us و eu شناسههای چندمنطقهای هستند و نامی مانند us-east5 یک منطقه واحد را مشخص میکند. از اکتبر 2026، Anthropic نقاط پایانی تکمنطقهای را فقط برای Claude Sonnet 4.6 و نسخههای قدیمیتر مستند کرده است؛ مدلهای جدیدتر از نقاط پایانی جهانی یا چندمنطقهای استفاده میکنند. طبق مستندات اکتبر 2026، نقاط پایانی چندمنطقهای و منطقهای 10 درصد گرانتر از حالت جهانی هستند. صورتحساب از طریق پروژه Google Cloud صادر میشود، بنابراین سهمیه (quota) و فاکتورها متعلق به Google هستند.
از تاریخ 27 اکتبر 2026، Anthropic دومین پیشنهاد Google Cloud را نیز مستند کرده است که ساختار درخواست آن متفاوت است. در Claude Models on Google Cloud (مدیریتشده توسط Anthropic)، خودِ Anthropic رابط Claude API را در claude.googleapis.com اجرا میکند که از طریق یک کلاینت AnthropicGoogleCloud در دسترس است. این سرویس همچنان با اعتبارنامههای Google Cloud از جمله ADC احراز هویت میشود، اما درخواست شبیه به API مستقیم است: model در بدنه باقی میماند و نسخه در هدر anthropic-version ارسال میشود. دسترسی از طریق نقشهای IAM اختصاصی آن (roles/claude.user و موارد مرتبط) فراهم میشود، راهاندازی آن یک سازمان Anthropic جدید برای پروژه ایجاد میکند و هزینهها از طریق Google Cloud Marketplace محاسبه میشود. اگر URLهای درخواست شما حاوی aiplatform هستند و به :rawPredict ختم میشوند، شما در مسیر مدیریتشده توسط Google هستید که در این بخش شرح داده شد.
مسیر 4: Microsoft Foundry همان مسیر Azure است
اگر به دنبال Claude در Azure هستید، این همان بخشی است که به آن نیاز دارید و یک مسیر پشتیبانیشده وجود دارد. Claude در Microsoft Foundry (که قبلاً Azure AI Foundry نامیده میشد) اجرا میشود و هزینهها از طریق Azure Marketplace در قالب Claude Consumption Units محاسبه میگردد. شما یک منبع Foundry ایجاد میکنید، یک مدل Claude را در آن مستقر (deploy) میکنید و با یک اندپوینت میزبانیشده در Azure به آدرس https://{resource}.services.ai.azure.com/anthropic/v1/* تماس میگیرید.
دو نوع اعتبارنامه کار میکند. اولی، کلیدی است که از تب Details در پورتال Foundry برای deployment صادر شده و در هدر api-key یا x-api-key ارسال میشود. دومی، توکن Microsoft Entra است که برای سرور گزینه بهتری است، زیرا کنترل دسترسی مبتنی بر نقش (RBAC) در Azure تعیین میکند چه کسی اجازه تماس با اندپوینت را دارد.
ACCESS_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
curl https://${RESOURCE}.services.ai.azure.com/anthropic/v1/messages \
-H "content-type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-d '{"model": "DEPLOYMENT_NAME", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'فیلد model حامل نام deployment شماست، نه شناسه مدل. این دو به صورت پیشفرض با هم مطابقت دارند، اما به محض اینکه خودتان نامی برای deployment انتخاب کنید، این تطابق از بین میرود؛ این موضوع علت معمول خطای Deployment not found در درخواستهایی است که از نظر ساختاری صحیح هستند. SDKهای پایتون و تایپاسکریپت، مقادیر ANTHROPIC_FOUNDRY_API_KEY و ANTHROPIC_FOUNDRY_RESOURCE را از محیط (environment) میخوانند. طبق مستندات 10 نوامبر 2026، پشتیبانی Foundry شامل هر هفت SDK رسمی است: C#، Go، Java، PHP، Python، Ruby و TypeScript. زبان Go از یک پکیج اختصاصی foundry (go get github.com/anthropics/anthropic-sdk-go/v2/foundry) استفاده میکند و Ruby در نسخه 2.5.0 از gem خود که در 4 نوامبر 2026 منتشر شد، یک Anthropic::FoundryClient اختصاصی دریافت کرد. پیش از آن انتشار، کدهای Ruby مجبور بودند کلاینت عمومی را به URL پایه Foundry اشاره دهند.
اشاره کردن یک کلاینت عمومی به URL پایه Foundry همچنان دارای پیچیدگیهایی است، چه در کدهای Ruby نوشتهشده قبل از نسخه 2.5.0 و چه در CLI مربوط به ant که نمونههای Foundry خودِ Anthropic نیز از آن استفاده میکنند. اگر اعتبارنامهها را به صورت صریح به کلاینت عمومی ارسال نکنید و ANTHROPIC_API_KEY یا ANTHROPIC_AUTH_TOKEN همچنان در محیط تنظیم شده باشند، کلاینت آنها را برداشته و اعتبارنامه Anthropic شما را به یک اندپوینت مایکروسافت ارسال میکند. متغیر را حذف کنید یا کلید/توکن Foundry را به صورت صریح به کلاینت بدهید. در Ruby، انتقال به Anthropic::FoundryClient که کلید Foundry یا یک ارائهدهنده توکن Entra را میپذیرد، راهکار تمیزتری است. توکن دسترسی Entra دارای طول عمر پیشفرض تصادفی بین 60 تا 90 دقیقه است، بنابراین یک پردازش طولانیمدت باید به جای دریافت توکن در زمان شروع، آن را بهطور خودکار تمدید (refresh) کند.
مدت اعتبار گواهیهای امنیتی روی سرور شما چقدر است؟
دادههای پشت این نمودار
[
{
"label": "Anthropic key, 30-day preset",
"max_lifetime_hours": 720
},
{
"label": "Anthropic key, 7-day preset",
"max_lifetime_hours": 168
},
{
"label": "AWS STS assumed role",
"max_lifetime_hours": 12
},
{
"label": "Bedrock short-term API key",
"max_lifetime_hours": 12
},
{
"label": "Entra ID access token, default upper bound",
"max_lifetime_hours": 1.5
},
{
"label": "Federated Anthropic token, default",
"max_lifetime_hours": 1
}
]این ارقام، سقفهای مجاز و مقادیر پیشفرضی هستند که توسط هر ارائهدهنده منتشر شده و در اکتبر 2026 بازخوانی شدهاند؛ اینها مقادیر اندازهگیریشده نیستند. اهمیت این ارقام تنها در یک مورد است: به شما میگویند که اگر یک گواهی امنیتی لو برود، تا چه مدت همچنان کار میکند و در این فاصله شما در حال شناسایی نشت اطلاعات هستید. توکن فدرال Anthropic در انتهای جدول بهطور پیشفرض تا 1 ساعت اعتبار دارد که البته به دو برابرِ باقیماندهٔ عمر توکنِ ارائهدهندهٔ هویت نیز محدود میشود. توکن دسترسی Microsoft Entra مقدار پیشفرض ثابتی ندارد: مایکروسافت برای هر توکن، طول عمری تصادفی بین 60 تا 90 دقیقه (بهطور میانگین 75 دقیقه) در نظر میگیرد که در جدول با سقف 1.5 ساعت نمایش داده شده است. این مقدار پیشفرض بسته به کلاینت، منبع (resource) و فعال بودن Conditional Access در tenant متغیر است. زمانی که هم کلاینت و هم منبع از Continuous Access Evaluation پشتیبانی کنند، Entra ممکن است طول عمر توکن را به 24 تا 28 ساعت افزایش دهد و در صورت وقوع رویدادهایی مانند غیرفعالشدن حساب، توکن را تقریباً بهصورت آنی ابطال کند. سیاست طول عمر توکن در یک tenant میتواند مقداری بین 10 دقیقه تا 23:59:59 را تعیین کند. SDKها توکنهای فدرال Anthropic را بهطور خودکار رفرش میکنند؛ در Foundry، برای رفرش کردن توکنها بهجای ارسال یک رشته توکن ثابت، یک ارائهدهنده توکن Entra پیکربندی کنید. یک قانون فدراسیون میتواند طول عمر توکن اختصاصی خود را بین یک دقیقه تا 24 ساعت تنظیم کند و ویزارد Connect workload در کنسول بهصورت پیشفرض 10 دقیقه را درج میکند، بنابراین بهجای فرض کردن مقدار پیشفرض، قانون مربوطه را مطالعه کنید. یک نقش فرضشده (assumed role) و یک کلید API کوتاهمدت Bedrock هر دو در سقف 12 ساعت قرار دارند. کلید API بلندمدت Bedrock جایی در این جدول ندارد زیرا سقف ثابتی برای آن تعریف نشده است: این کلید تا زمان انقضایی که هنگام ایجاد انتخاب شده معتبر است، یا اگر CredentialAgeDays در فراخوانی API حذف شده باشد، هرگز منقضی نمیشود؛ به همین دلیل است که AWS استفاده از آن را فقط برای مراحل اکتشافی توصیه میکند. کلیدی که با پیشفرض 30 روزه ایجاد شده باشد، به مدت 720 ساعت معتبر باقی میماند و این همان گواهی امنیتی است که به مدت یک ماه در فایلی روی سرور شما باقی میماند.
محل نگهداری اعتبارنامهها در VPS
رمز را در فایلی قرار دهید که فقط root امکان خواندن آن را داشته باشد و اجازه دهید systemd آن را به پردازش مربوطه تحویل دهد. این روش از تمامی نسخههای SDK عمر طولانیتری دارد، بنابراین ارزش دارد که یکبار به درستی انجام شود.
sudo useradd --system --home /opt/claude-app --shell /usr/sbin/nologin claudeapp
sudo install -d -m 700 -o root -g root /etc/claude-app
sudo install -m 600 -o root -g root /dev/null /etc/claude-app/env
sudoedit /etc/claude-app/envاین فایل شامل خطوط ساده KEY=value است. بدون export، بدون کوتیشن و بدون سینتکس shell، زیرا systemd خودش آن را پارس میکند و از طریق shell اجرا نمیکند.
ANTHROPIC_API_KEY=sk-ant-api03-REPLACE-ME
CLAUDE_MODEL=REPLACE-ME[Unit]
Description=Claude API service
After=network-online.target
[Service]
User=claudeapp
EnvironmentFile=/etc/claude-app/env
ExecStart=/opt/claude-app/venv/bin/python -m claude_app
Restart=on-failure
[Install]
WantedBy=multi-user.targetsystemd فایل EnvironmentFile= را به عنوان root میخواند، پیش از آنکه دسترسی را به User=claudeapp کاهش دهد، بنابراین اکانت سرویس هرگز نیازی به دسترسی خواندن فایل ندارد. حالت 600 با مالکیت root کافی است، به همین دلیل است که دستور install در بالا آن را به این شکل تنظیم میکند. آن را با sudo systemctl enable --now claude-app شروع کنید و سپس با systemctl status claude-app تأیید کنید که unit به وضعیت active (running) رسیده است و در یک حلقه بازراهاندازی (loop) گیر نکرده است.
چهار مورد را که باید از آنها اجتناب کنید، به همراه دلیلی که خودتان میتوانید بررسی کنید:
- کلید را با
Environment=داخل فایل unit ننویسید. یک unit تحت/etc/systemd/systemبرای همه کاربران قابل خواندن است، بنابراینsystemctl cat claude-appرمز را برای هر کاربر محلی نمایش میدهد. - آن را commit نکنید.
.gitignoreیک فایل جدید را از commit دور نگه میدارد و هیچ کاری برای فایلی که قبلاً commit شده انجام نمیدهد، زیرا تاریخچه git هر چیزی را که به آن داده شده حفظ میکند. - آن را در image کانتینر قرار ندهید. مقادیر
ENVدر پیکربندی image باقی میمانند و آرگومانهای build در تاریخچه image یا متادیتای منشأ قابل مشاهده هستند. حذف فایل در لایههای بعدی، آن را از لایههای قبلی پاک نمیکند. رمزها را در زمان اجرا با--env-fileیا یک فایل mount شده ارسال کنید. - محیط پردازش (process environment) را از دید root خصوصی فرض نکنید.
sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n'کلید را نمایش میدهد. خودِ دستور خواندن فایل بهsudoنیاز دارد؛ تغییر مسیر ورودی shell (shell input redirection) پیش ازsudoاجرا میشود و از مجوزهای اکانت فعلی شما استفاده میکند. هدف این است که رمز از سایر اکانتهای موجود در سیستم دور نگه داشته شود، نه از root، که در هر صورت میتواند آن را بخواند.
نکته آخر، مرزِ دستاوردهای این طراحی را مشخص میکند. فایلِ محدود به root از کلید ذخیرهشده محافظت میکند، اما هر کدی که با اکانت سرویس اجرا شود میتواند محیط پردازش را بخواند و پردازشهای فرزند نیز آن را به ارث میبرند. اگر پردازش کدی را اجرا میکند که شما ننوشتهاید، این کانتینر مناسب نیست، زیرا هر چیزی که پردازش بتواند اجرا کند، قادر به خواندن محیط خودش است. دور نگه داشتن رمزها از دسترس یک عامل هوش مصنوعی این مورد را پوشش میدهد که مسئلهای متفاوت با پاسخی متفاوت است.
چگونه کلید را بدون قطعی سرویس چرخش (rotate) دهم؟
ابتدا کلید جدید را جایگزین کنید و سپس کلید قبلی را ابطال نمایید. راهکار ریاستارت سرویس که در ادامه آمده است، باعث وقفه کوتاهی در سرویس میشود؛ برای دسترسی بدون وقفه، به یک نمونه (instance) دیگر نیاز دارید تا در حین ریاستارت، درخواستها را مدیریت کند.
- کلید جدید را در کنسول و در همان workspace کلید قدیمی ایجاد کنید.
- آن را با استفاده از
sudoeditدر/etc/claude-app/envبنویسید. - دستور
sudo systemctl restart claude-appرا اجرا کنید. - اطمینان حاصل کنید که سرویس به درخواستها پاسخ میدهد، سپس کلید قدیمی را در کنسول ابطال (revoke) کنید.
فایل EnvironmentFile هنگام شروع unit خوانده میشود، بنابراین فرآیندی که در حال اجراست، مقداری را که در لحظه راهاندازی دریافت کرده است حفظ میکند. دستور systemctl daemon-reload فایلهای unit را دوباره میخواند اما تغییری در محیط (environment) فرآیند در حال اجرا ایجاد نمیکند، بنابراین تنها با ریاستارت است که کلید جدید اعمال میشود. ابطال کلید در مرحله 1 به جای مرحله 4، باعث ایجاد قطعی سرویس تا زمان اجرای مرحله 3 خواهد شد.
مسیرهای ابری (cloud routes) در سمت ارائهدهنده چرخش داده میشوند. یک کاربر IAM از دو کلید دسترسی فعال بهطور همزمان پشتیبانی میکند؛ بنابراین کلید دوم را ایجاد و مستقر کنید، سپس کلید اول را حذف نمایید. کلید حساب کاربری سرویس گوگل (Google service account) نیز به همین روش چرخش داده میشود. یک منبع Foundry دارای دو کلید است و بازتولید (regenerate) یکی از آنها باعث میشود مقدار قدیمی آن بلافاصله از کار بیفتد؛ بنابراین پیش از بازتولید کلیدی که سرویس از آن استفاده میکند، سرویس را به کلید دیگر منتقل کنید. توکنهای Entra و توکنهای فدرال Anthropic نیازی به چرخش دستی ندارند و این قویترین دلیل برای استفاده از آنها در صورت امکان است.
زمانی که در کنسول هستید، یک سقف هزینه (spend limit) برای workspace تعیین کنید. کلید لو رفته پیش از هر چیز دیگری، هزینهبر است و محدود کردن هزینههای مجاز برای یک عامل روی VPS شما را با این کنترلها آشنا میکند.
چرا کلاینت من خطای 401 یا 403 برمیگرداند؟
خطای 401 همراه با authentication_error در API مستقیم. کلید اشتباه است، ابطال شده یا تاریخ انقضای آن گذشته است. تاریخ انقضا موردی است که معمولاً نادیده گرفته میشود، زیرا کد تغییری نکرده و درخواست دیروز بهدرستی کار میکرده است. ستون انقضای کلید را در Console بررسی کنید یا expires_at را از Admin API بخوانید؛ جایی که برای کلیدهای بدون انقضا مقدار null درج شده است. همچنین، کلید شخصی با خروج مالک آن از سازمان، از کار میافتد.
SDK تنظیمات فدراسیون شما را نادیده میگیرد و به جای آن از یک کلید استفاده میکند. ANTHROPIC_API_KEY و ANTHROPIC_AUTH_TOKEN در اولویتبندی اعتبارنامهها بالاتر از فدراسیون قرار دارند، بنابراین هر کدام از آنها فدراسیون را تحتالشعاع قرار میدهند. نکته دقیق اینجاست: متغیری که به صورت رشته خالی (empty string) صادر شده باشد، همچنان جایگاه خود را اشغال میکند؛ بنابراین ANTHROPIC_API_KEY="" باعث میشود SDK به جای عبور از آن، با یک کلید خالی احراز هویت کند. از unset ANTHROPIC_API_KEY استفاده کنید.
خطای 401 با پیام ساده Authentication failed در فدراسیون. این پیام برای تمام دلایل احتمالی بهصورت عمدی یکسان در نظر گرفته شده است تا فراخواننده نتواند با خواندن متن خطا، پیکربندی قوانین شما را بررسی (probe) کند. دلیل واقعی در صفحه تاریخچه احراز هویت در Console ثبت شده است. به جای حدس زدن درباره JWT، از آنجا شروع کنید.
خطای 403 در Foundry. توکن احراز هویت شده است، اما حساب Azure شما فاقد نقشی است که اجازه این فراخوانی را بدهد. یک نقش Azure RBAC مانند Foundry User (که قبلاً Azure AI User نامیده میشد) یا Cognitive Services User را به هویتی که درخواست را ارسال میکند، اختصاص دهید.
هر موردی در Bedrock. برای احراز هویت SigV4، ابتدا aws sts get-caller-identity را به عنوان کاربر سرویس اجرا کنید. این دستور مشخص میکند که آیا سیستم اصلاً اعتبارنامههای AWS قابل استفاده دارد یا خیر؛ این کار مشکل اعتبارنامه را از مشکل دسترسی به مدل یا عدم تطابق منطقه (region) جدا میکند. تا تاریخ 29 October 2026، سرویس AWS دسترسی به بسیاری از مدلها را در اولین استفاده در مناطق تجاری با مجوزهای لازم AWS Marketplace فعال میکند، اما برخی مدلها به دسترسی جداگانه در سطح حساب نیاز دارند. مدلهای Anthropic که از طریق مسیر InvokeModel فراخوانی میشوند، ابتدا به یک فرم "مورد استفاده" (use case form) برای هر حساب نیاز دارند (یا یک بار برای کل یک AWS Organization، اگرچه مناطق opt-in دوباره به آن نیاز دارند) و تا زمانی که این فرم تایید نشود، فراخوانی مقدار AccessDeniedException را برمیگرداند. AWS مستند کرده است که این فرم برای endpoint مربوط به bedrock-mantle اعمال نمیشود. اولین فراخوانی به یک مدل در یک حساب باعث میشود Bedrock اشتراک AWS Marketplace را در پسزمینه شروع کند و آن اشتراک به هویتی نیاز دارد که دارای مجوزهای aws-marketplace:Subscribe، aws-marketplace:Unsubscribe و aws-marketplace:ViewSubscriptions باشد. فقدان مجوزها لزوماً باعث شکست آن اولین فراخوانی نمیشود: AWS مستند کرده است که فراخوانیها ممکن است تا 15 دقیقه در حالی که اشتراک در حال تنظیم است موفق باشند، و پس از شکست اشتراک، فراخوانیهای بعدی همان خطای AccessDeniedException را برمیگردانند. سرویسی که در چند دقیقه اول کار میکرد و سپس دچار خطا شد، به این موضوع اشاره دارد، نه به اعتبارنامهها. پس از اعطای مجوزها، AWS تا 2 دقیقه زمان برای تکمیل اشتراک در نظر میگیرد. مدلی که در منطقهای که فراخوانی میکنید ارائه نشده باشد، فارغ از معتبر بودن اعتبارنامهها، با شکست مواجه میشود.
FAQ
آیا برای استفاده از Claude در Bedrock یا Vertex به کلید API شرکت Anthropic نیاز دارم؟
خیر. در Amazon Bedrock، کیت توسعه نرمافزار (SDK) درخواستها را با استفاده از اعتبارنامههای AWS و پروتکل SigV4 امضا میکند یا یک کلید API مخصوص Bedrock میفرستد. در Google Cloud نیز از توکن دسترسی Google که از طریق Application Default Credentials پیدا میشود، استفاده میگردد. در هیچکدام از این دو حالت، کلید محرمانهای که توسط Anthropic صادر شده باشد وجود ندارد و هزینهها بهجای حساب Anthropic، به حساب ابری شما منظور میشود. به همین دلیل است که باقی ماندن کلید Anthropic در ANTHROPIC_API_KEY روی این میزبانها یک ریسک امنیتی محسوب میشود: یک کلاینت عمومی که به سمت یک endpoint ابری تنظیم شده باشد، بهراحتی آن کلید را به مقصد میفرستد.
آیا Claude در Azure در دسترس است؟
بله، از طریق Microsoft Foundry که قبلاً Azure AI Foundry نام داشت. شما یک منبع Foundry ایجاد میکنید، یک مدل Claude را در آن مستقر (deploy) میکنید و با استفاده از یک کلید صادر شده توسط Azure در هدر api-key یا یک توکن bearer از Microsoft Entra، متد https://{resource}.services.ai.azure.com/anthropic/v1/messages را فراخوانی میکنید. هزینهها از طریق Azure Marketplace و با واحد Claude Consumption Units محاسبه میشود. فیلد model در بدنه درخواست باید شامل نام deployment شما باشد؛ این نام تنها در صورتی با شناسه مدل یکی است که هنگام ایجاد deployment، نام پیشفرض را تغییر نداده باشید؛ چرا که پس از ایجاد، امکان تغییر نام وجود ندارد.
کلید API مربوط به Claude را کجا در سرور Linux ذخیره کنم؟
در فایلی که مالک آن root است و دسترسی آن روی 600 تنظیم شده، و از طریق EnvironmentFile= در یک unit فایل systemd بارگذاری میشود. systemd این فایل را پیش از تغییر کاربر به User= تعیینشده برای unit، با دسترسی root میخواند؛ بنابراین حساب کاربری سرویس نیازی به دسترسی مستقیم به آن فایل ندارد. کلید را خارج از مخزن کد (repository)، خارج از خودِ unit فایل (که برای همه قابل خواندن است و توسط systemctl cat نمایش داده میشود) و خارج از تنظیمات، لایهها و متادیتای ساخت (build) ایمیج کانتینر نگه دارید.
چرا درخواست API من به Claude بدون هیچ تغییری، خطای 401 برمیگرداند؟
کلیدی که به تاریخ انقضای تعیینشده در زمان ساخت رسیده باشد، خطای 401 برمیگرداند. تاریخ انقضا در زمان ایجاد کلید تعیین میشود، پس از آن قابل ویرایش نیست و کلیدهای کوتاهمدت بدون ارسال ایمیل هشدار منقضی میشوند. کلید منقضیشده قابل فعالسازی مجدد نیست؛ بنابراین یک کلید جایگزین بسازید، آن را در فایل محیطی (environment file) بنویسید، سرویس را restart کنید و سپس کلید قدیمی را ابطال (revoke) کنید. اگر از معتبر بودن کلید اطمینان دارید، بررسی کنید که یک اعتبارنامه قدیمی (stale) باعث تداخل نشده باشد: مقدار ANTHROPIC_API_KEY حتی اگر به صورت یک رشته خالی تنظیم شده باشد، بر منابع federation و profile که در اولویتهای پایینتر هستند، ارجحیت دارد.