SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor

Xác thực Claude API với key, Bedrock, Vertex, Foundry

Chọn đúng credential cho Claude API trên VPS: Anthropic key, AWS IAM, Google ADC hay Microsoft Entra. Biết khi nào Bedrock không dùng Anthropic key.

Các phương thức xác thực Claude API

Xác thực Claude API phụ thuộc vào một quyết định: client gửi credential nào qua mạng. Anthropic liệt kê Claude API trực tiếp và 5 nền tảng cloud: Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Google managed), Claude Models on Google Cloud (Anthropic managed) và Microsoft Foundry. Anthropic API trực tiếp nhận API key hoặc token có thời hạn ngắn trong header Authorization: Bearer, đồng thời vẫn chấp nhận API key trong header cũ x-api-key. Amazon Bedrock hỗ trợ ký request AWS và Bedrock API key; trong mô hình này không có Anthropic key nào được sử dụng. Google Cloud gửi Google access token có thời hạn ngắn. Microsoft Foundry nhận key do Azure cấp hoặc Microsoft Entra token. 4 phần bên dưới trình bày các cách cấu hình credential này. Hai dịch vụ do Anthropic quản lý trên AWS và Google Cloud được giải thích cùng với các dịch vụ cloud tương ứng.

Hướng dẫn này dành cho việc tích hợp SDK (software development kit) vào một service chạy trên Linux server. Nếu bạn đang cấu hình công cụ dòng lệnh Claude Code, các biến và quy trình sẽ khác: xem trỏ Claude Code đến Bedrock hoặc Vertex. Nếu service chưa tồn tại, hãy tạo trước bằng tạo ứng dụng Claude API đầu tiên trên VPS, rồi quay lại đây để cấu hình credential.

Mọi nội dung bên dưới đã được đối chiếu với tài liệu platform của Anthropic vào tháng 8 năm 2026 và đối chiếu lại với tài liệu của từng provider vào ngày 16 tháng 10 năm 2026; thông tin về quyền truy cập model trên Bedrock đã được đối chiếu lại với tài liệu AWS vào ngày 19 tháng 10 năm 2026. Các trang của Anthropic về cả 4 phương thức, API key và API version đã được đối chiếu lại vào ngày 27 tháng 10 năm 2026. Các trang của Anthropic về Microsoft Foundry, cả 2 endpoint Bedrock, phương thức Google-managed, Claude Platform on AWS, authentication, Workload Identity Federation và API version đã được đối chiếu lại vào ngày 10 tháng 11 năm 2026, cùng với changelog của Ruby SDK. Model identifier, giá, phiên bản SDK và dạng endpoint đều có thể thay đổi, nên hướng dẫn này liên kết đến trang của các provider thay vì in các giá trị có thể nhanh chóng lỗi thời.

Tuyến 1: API key của Anthropic

Đây là đường đi trực tiếp và là cách duy nhất trong đó Anthropic cấp secret. Request đi đến endpoint Messages trên API host của Anthropic, và mỗi request đều gửi 3 header.

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"}]}'

Thay MODEL_ID bằng identifier hiện tại từ tổng quan models của Anthropic. Response hợp lệ là JSON chứa một array content và một object usage. Key sai hoặc hết hạn trả về HTTP 401 kèm authentication_error. Thiếu header anthropic-version là một lỗi riêng, vì header này bắt buộc trong mọi request; SDK tự đặt header này cho bạn. Tính đến tháng 10 năm 2026, tài liệu của Anthropic giới thiệu Authorization: Bearer là cách chính để gửi key và gọi x-api-key là legacy, nhưng cả hai đều được chấp nhận, nên command ở trên vẫn hoạt động. Các phiên bản major hiện tại của SDK cũng gửi key dưới dạng Authorization: Bearer, vì vậy proxy hoặc gateway đọc X-Api-Key cần được thay đổi khi bạn nâng cấp. Phiên bản 2023-06-01 trong command vẫn được chấp nhận; phiên bản API mới nhất của Anthropic là 2026-10-21. Các phiên bản SDK đó gửi phiên bản này theo mặc định và phiên bản này từ chối một số request parameter cũ như temperature.

Việc khởi tạo client là cách ngắn nhất trong các cách thiết lập này, vì không có gì cần tự khởi tạo. Mọi SDK chính thức đều tự đọc ANTHROPIC_API_KEY từ 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)

Nên đặt model identifier trong environment cùng với key. Tên model thay đổi theo lịch mà bạn không kiểm soát được, và việc redeploy code chỉ để sửa một chuỗi là công việc có thể tránh.

Key được tạo trong Console. Khi tạo key, bạn chọn thời hạn: các preset 3 giờ, 1 ngày, 7 ngày hoặc 30 ngày, thời lượng tùy chỉnh, hoặc Never, tùy theo chính sách thời hạn tối đa của tổ chức. Thời hạn được cố định khi tạo và không thể thay đổi sau đó. Anthropic gửi email cho người tạo key trước khi key có thời hạn dài hết hạn, nhưng key có thời hạn ngắn sẽ hết hạn mà hoàn toàn không có email cảnh báo. Key hết hạn trả về 401 và không thể kích hoạt lại, nên cách xử lý luôn là tạo key mới.

Direct API không yêu cầu chọn region, và chi phí được tính trực tiếp cho organization Anthropic của bạn. Workspace giới hạn key trong một project, đây là cách rõ ràng nhất để biết một service duy nhất tiêu tốn bao nhiêu. Khi tạo key cho server, hãy giới hạn key trong workspace của server: key của personal account hoặc service account không được giới hạn trong workspace phải gửi header anthropic-workspace-id trong mọi request, nếu không API sẽ trả về 400 kèm invalid_request_error. Với service, hãy chọn key của service account, vì personal key sẽ ngừng hoạt động khi người tạo key rời organization. Để xem cách tính chi phí, xem cách giá API theo token so với subscription.

Có thêm một tùy chọn phù hợp với phần này vì nó loại bỏ hoàn toàn static secret. Workload Identity Federation cho phép workload đổi token OpenID Connect (OIDC) từ một identity provider mà bạn đã tin cậy lấy Anthropic token có thời hạn ngắn tại POST /v1/oauth/token, và SDK sẽ refresh token đó trước khi hết hạn. Không có chuỗi sk-ant-api... nào được tạo hoặc sao chép ở bất kỳ đâu. Cách này phù hợp với Kubernetes, GitHub Actions và cloud VM, vì các môi trường đó đã có platform identity. VPS thông thường thường không có issuer như vậy, nên trên máy đó, API key trong một file là phương án thực tế; phần còn lại của hướng dẫn này cũng xử lý theo cách đó.

Route 2: Thông tin xác thực AWS trên Amazon Bedrock

Trên Bedrock, bạn hoàn toàn không cần Anthropic key. Với thông tin xác thực AWS, SDK ký từng HTTP request bằng AWS Signature Version 4 (SigV4), còn AWS quyết định caller đó có được phép invoke model hay không.

pip install -U "anthropic[bedrock]"
aws sts get-caller-identity

aws sts get-caller-identity in số tài khoản và ARN (Amazon Resource Name) của identity mà thông tin xác thực của bạn phân giải tới. Hãy chạy lệnh này trước mọi thao tác khác khi dùng SigV4. Với SigV4, SDK phân giải credentials từ constructor, credentials trong environment và standard AWS credential chain; việc chọn region là một bước riêng. Trong Python AnthropicBedrock client, API key của Bedrock được cung cấp qua api_key hoặc AWS_BEARER_TOKEN_BEDROCK sẽ gây ra ValueError nếu bạn đồng thời truyền aws_access_key, aws_secret_key, aws_session_token hoặc aws_profile. Nếu không truyền các argument tường minh này, key sẽ chọn bearer authentication thay vì AWS credential chain. TypeScript client ưu tiên Bedrock API key hơn AWS credentials tường minh. Lệnh STS không kiểm tra bearer authentication.

Khi khởi tạo client, chỉ class và một argument thay đổi.

from anthropic import AnthropicBedrock

client = AnthropicBedrock(aws_region="us-east-1")

AnthropicBedrock điều khiển tích hợp InvokeModel của Bedrock. Tính đến tháng 10 năm 2026, Anthropic cũng có tài liệu về Claude trên Amazon Bedrock, với endpoint Messages API tại https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages cho Claude Opus 4.7 và các model mới hơn, được truy cập thông qua AnthropicBedrockMantle client trong cùng package. Endpoint này hỗ trợ AWS credentials và Bedrock bearer tokens; yêu cầu về model access giữa hai endpoint khác nhau, như giải thích bên dưới.

Hãy chú ý đến thay đổi trong dòng pip install -U đó. Tính đến ngày 27 tháng 10 năm 2026, SDK mới nhất mặc định gửi API version 2026-10-21, kể cả khi dùng qua Bedrock. Anthropic ghi rõ rằng các model ID có version trong ARN được liệt kê cho Claude Opus 4.6 và các model cũ hơn không hỗ trợ version đó trên Bedrock và có thể trả về lỗi 400. Nếu một service gọi một trong các model này, hãy giữ SDK ở version hiện đang chạy và pin version đó, hoặc trước tiên chuyển service sang model Claude 4.7 hoặc mới hơn.

Region không còn là giá trị phụ ở đây. Bedrock endpoint tồn tại theo từng region, các Claude model được cung cấp khác nhau giữa các region, và region là một phần của chữ ký SigV4. Vì vậy, chữ ký được tính cho một region sẽ bị region khác từ chối. Hãy đặt AWS_REGION một cách tường minh trong environment của service, vì các SDK không thống nhất về hành vi khi bạn bỏ trống giá trị này. Theo tài liệu tháng 10 năm 2026, Python AnthropicBedrock client đọc AWS_REGION hoặc AWS_DEFAULT_REGION, sau đó dùng region của boto3 session hoặc AWS profile, bao gồm ~/.aws/config, và gây ra ValueError nếu không phân giải được giá trị nào. TypeScript client đọc AWS_REGION, fallback sang us-east-1 khi giá trị này chưa được đặt, và không đọc ~/.aws/config để lấy region. Vì vậy AWS CLI có thể list thành công các Claude model trên cùng máy mà một Node process lại gọi nhầm region: CLI đã đọc file cấu hình của bạn còn client thì không.

Trên EC2, bạn gắn một IAM (identity and access management) role và không có secret nào được ghi xuống disk, vì instance metadata service cung cấp temporary credentials cho SDK. VPS bên ngoài AWS không có instance role cũng không có metadata service. Khi đó, bạn phải chọn giữa việc đặt cặp access key dài hạn của IAM user trên máy, thuộc cùng loại secret với Anthropic key, và federation: xác thực với identity provider của bạn, gọi AWS STS (security token service), rồi dùng temporary credentials mà service này trả về. Bedrock cũng chấp nhận Bedrock API keys, là bearer tokens được truyền qua AWS_BEARER_TOKEN_BEDROCK, và AWS có tài liệu về 2 loại. Short-term key có hiệu lực tối đa 12 giờ, hoặc trong thời lượng của session đã tạo key nếu thời lượng đó ngắn hơn; key này kế thừa quyền của IAM identity đã tạo nó và là loại AWS khuyến nghị dùng trong production. Long-term key có hiệu lực đến thời điểm hết hạn bạn chọn khi tạo key, chẳng hạn 30 hoặc 90 ngày với --credential-age-days, hoặc không hết hạn nếu bỏ qua API parameter đó; Console tạo một IAM user đứng sau key này, và AWS chỉ khuyến nghị dùng loại key này để thử nghiệm. Long-term key chỉ hoạt động trong region nơi nó được tạo; dùng key này ở region khác sẽ trả về Credential should be scoped to a valid region.

Chi phí được tính vào AWS account của bạn thay vì Anthropic. Đây thường là lý do chính để chọn cách này. Theo tài liệu tháng 10 năm 2026, regional endpoint có phụ phí 10% so với global endpoint. Claude Platform trên AWS là một product riêng: Anthropic vận hành product này, AWS tính phí qua AWS Marketplace, và product xác thực bằng SigV4 hoặc API key được tạo trong AWS Console; key từ Claude Console không hoạt động ở đây. Product này dùng AnthropicAWS client, được Anthropic đánh dấu là beta. Có một lỗi Bedrock đáng chú ý vì trông giống lỗi permissions nhưng thực tế không phải: 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. Đó là lỗi model routing, và thay đổi credential sẽ không sửa được lỗi này.

Route 3: Google credentials trên Vertex AI

Tài liệu của Anthropic hiện gọi route này là Claude Models trên Google Cloud (Google managed), được Google vận hành như một phần của Agent Platform, tên mới của Google cho nền tảng phát triển từ Vertex AI. Host aiplatform.googleapis.com, extra anthropic[vertex] và class AnthropicVertex được hiển thị bên dưới không thay đổi.

Google Cloud dùng Application Default Credentials (ADC), một thứ tự tìm kiếm cố định mà các thư viện xác thực của Google tuân theo để tìm credential mà bạn không cần chỉ định. ADC kiểm tra GOOGLE_APPLICATION_CREDENTIALS trước, sau đó đến file do gcloud auth application-default login ghi, rồi đến service account được gắn qua metadata server.

pip install -U "anthropic[vertex]"
gcloud auth application-default login

Trên workstation, lệnh đăng nhập đó ghi $HOME/.config/gcloud/application_default_credentials.json và bạn đã hoàn tất. Trên server, tránh lưu credential của người dùng; command này cũng hỗ trợ service account impersonation. Khi chạy ngoài Google Cloud, cũng không có Google metadata server, nên dùng GOOGLE_APPLICATION_CREDENTIALS để trỏ ADC đến file cấu hình Workload Identity Federation hoặc file service account key. File JSON của service account key là secret có thời hạn dài và phải được xử lý đúng theo hướng dẫn ở phần sau. Khi chạy trong Google Cloud, hãy gắn service account vào VM; khi đó không có file nào cần bảo vệ. Identity mà ADC tìm thấy phải có IAM role chứa permission aiplatform.endpoints.predict, chẳng hạn Agent Platform User (roles/aiplatform.user).

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="my-project", region="global")

Có 2 điểm thay đổi khi bạn bỏ qua SDK và gọi HTTP trực tiếp. Model identifier được chuyển từ request body vào URL path, còn anthropic_version được chuyển từ header vào body. Tính đến 27 October 2026, tài liệu của Anthropic chấp nhận vertex-2023-10-16 tại vị trí đó hoặc API version mới hơn là 2026-10-21. Credential là Google access token thông thường. Trong command bên dưới, gcloud auth print-access-token dùng login riêng của gcloud CLI thay vì ADC, nên hãy chạy gcloud auth login hoặc gcloud init trước trên máy bạn dùng để test.

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 là một tham số chính thức. global định tuyến động để tăng khả năng sẵn sàng, us và eu là các multi-region identifier, còn tên như us-east5 cố định một region duy nhất. Tính đến October 2026, Anthropic chỉ ghi nhận single-region endpoint cho Claude Sonnet 4.6 và các model cũ hơn; các model mới hơn dùng global hoặc multi-region endpoint. Theo tài liệu tháng October 2026, multi-region và regional endpoint có giá cao hơn global 10%. Việc billing đi qua Google Cloud project, nên quota và hóa đơn thuộc về Google.

Tính đến 27 October 2026, Anthropic cũng ghi nhận một offering Google Cloud thứ hai, với request shape khác. Trong Claude Models trên Google Cloud (Anthropic managed), Anthropic tự vận hành Claude API tại claude.googleapis.com, được truy cập thông qua client AnthropicGoogleCloud. Route này vẫn xác thực bằng Google Cloud credential, bao gồm ADC, nhưng request có dạng giống direct API: model vẫn nằm trong body và version được truyền trong header anthropic-version. Quyền truy cập đến từ IAM role riêng của route này (roles/claude.user và các role liên quan), quá trình thiết lập tạo một organization Anthropic mới cho project, còn usage được tính phí qua Google Cloud Marketplace. Nếu URL request của bạn chứa aiplatform và kết thúc bằng :rawPredict, bạn đang dùng Google-managed route được mô tả trong phần này.

Phương thức 4: Microsoft Foundry là phương thức Azure

Nếu bạn đã tìm Claude trên Azure, đây là phần bạn cần đọc và đây là một phương thức được hỗ trợ. Claude chạy trong Microsoft Foundry (trước đây là Azure AI Foundry), với chi phí được tính qua Azure Marketplace theo Claude Consumption Units. Bạn tạo một Foundry resource, deploy một Claude model trong đó, rồi gọi endpoint được host trên Azure tại https://{resource}.services.ai.azure.com/anthropic/v1/*.

Có 2 credential được hỗ trợ. Cách thứ nhất là key do Azure cấp trong tab Details của deployment trên Foundry portal, được gửi trong header api-key hoặc x-api-key. Cách thứ hai là Microsoft Entra token. Đây là lựa chọn phù hợp hơn trên server vì Azure role-based access control sẽ quyết định ai được phép gọi endpoint.

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"}]}'

Trường model chứa tên deployment, không phải model identifier. Theo mặc định, 2 giá trị này giống nhau. Chúng sẽ khác ngay khi bạn tự đặt tên deployment, đây là nguyên nhân thường gặp nhất của lỗi Deployment not found dù request không có lỗi khác. Python và TypeScript SDK đọc ANTHROPIC_FOUNDRY_API_KEY và ANTHROPIC_FOUNDRY_RESOURCE từ environment. Theo tài liệu ngày 10 tháng 11 năm 2026, Foundry hỗ trợ cả 7 SDK chính thức: C#, Go, Java, PHP, Python, Ruby và TypeScript. Go dùng package foundry riêng (go get github.com/anthropics/anthropic-sdk-go/v2/foundry), còn Ruby đã có Anthropic::FoundryClient riêng trong version 2.5.0 của gem, phát hành ngày 4 tháng 11 năm 2026. Trước version đó, mã Ruby phải trỏ generic client đến Foundry base URL.

Việc trỏ generic client đến Foundry base URL vẫn có một điểm dễ lỗi, dù đó là mã Ruby được viết trước version 2.5.0 hay CLI ant, vốn được gọi theo cách này trong các ví dụ Foundry của chính Anthropic. Nếu bạn không truyền credential rõ ràng cho generic client và ANTHROPIC_API_KEY hoặc ANTHROPIC_AUTH_TOKEN vẫn được đặt trong environment, client sẽ tự đọc giá trị đó và gửi Anthropic credential của bạn đến Microsoft endpoint. Hãy unset biến này hoặc truyền rõ Foundry key hay token cho client. Với Ruby, chuyển sang Anthropic::FoundryClient là cách sửa gọn hơn; package này nhận Foundry key hoặc Entra token provider. Entra access token có thời hạn mặc định ngẫu nhiên từ 60 đến 90 phút, nên process chạy lâu phải refresh token thay vì giữ nguyên một token được lấy lúc khởi động.

Credential trên server của bạn tồn tại bao lâu?

Biểu đồDocumented credential lifetime by route, hours
Dữ liệu đằng sau biểu đồ này
[
  {
    "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
  }
]

Đây là các giới hạn tối đa và giá trị mặc định do từng nhà cung cấp công bố, được đọc vào tháng 10 năm 2026, không phải số liệu đo thực tế. Chúng quan trọng vì một lý do: chúng cho biết credential bị lộ vẫn hoạt động trong bao lâu, trong khi bạn đang phát hiện credential đó đã bị lộ. Anthropic token liên kết danh tính ở cuối biểu đồ mặc định có thời hạn tối đa 1 giờ, đồng thời bị giới hạn ở mức gấp đôi thời gian còn lại của token từ identity provider. Microsoft Entra access token không có một giá trị mặc định duy nhất: Microsoft cấp cho mỗi token một thời hạn ngẫu nhiên từ 60 đến 90 phút, trung bình là 75 phút. Trên biểu đồ, thời hạn này được thể hiện ở giới hạn trên 1.5 giờ. Giá trị mặc định cũng thay đổi tùy theo client, resource và việc Conditional Access có được bật trong tenant hay không. Khi cả client và resource đều hỗ trợ Continuous Access Evaluation, Entra có thể kéo dài thời hạn lên 24 đến 28 giờ và thay vào đó revoke token gần như theo thời gian thực khi xảy ra các sự kiện như vô hiệu hóa account. Tenant token lifetime policy có thể đặt thời hạn trong khoảng từ 10 phút đến 23:59:59. SDK tự động refresh federated Anthropic token. Trên Foundry, hãy cấu hình Entra token provider để refresh token thay vì truyền một chuỗi token cố định. Federation rule có thể tự đặt thời hạn token trong khoảng từ một phút đến 24 giờ. Console Connect workload wizard điền sẵn 10 phút, vì vậy hãy đọc rule thay vì giả định giá trị mặc định. Assumed role và Bedrock short-term API key đều có thời hạn 12 giờ. Bedrock long-term API key không xuất hiện trên biểu đồ vì không có giới hạn tối đa cố định: key tồn tại đến thời điểm hết hạn được chọn khi tạo, hoặc không hết hạn nếu CredentialAgeDays bị bỏ qua trong API call. Vì lý do này, AWS chỉ khuyến nghị dùng key này cho mục đích khám phá. Key được tạo bằng preset 30 ngày vẫn hợp lệ trong 720 giờ. Đây là credential nằm trong một file trên server của bạn suốt một tháng.

Vị trí lưu credential trên VPS

Đặt secret trong một file chỉ root có thể đọc, rồi để systemd truyền secret đó cho process. Phần này không phụ thuộc vào từng phiên bản SDK, nên bạn chỉ cần làm một lần cho đúng.

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

File chứa các dòng plain KEY=value. Không có export, không có dấu ngoặc kép và không có cú pháp shell, vì systemd tự parse file thay vì chạy file qua 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.target

systemd đọc EnvironmentFile= với quyền root trước khi hạ quyền xuống User=claudeapp, nên service account không bao giờ cần quyền đọc file. File có mode 600 và thuộc sở hữu của root là đủ. Vì vậy, lệnh install ở trên đặt file theo cách đó. Khởi động service bằng sudo systemctl enable --now claude-app, rồi xác nhận bằng systemctl status claude-app rằng unit đã đạt trạng thái active (running) thay vì khởi động lại liên tục.

Có 4 điều cần tránh. Mỗi điều đều có lý do mà bạn có thể tự kiểm tra:

  • Không ghi key bằng Environment= bên trong unit file. Unit nằm dưới /etc/systemd/system có quyền đọc cho mọi user, nên systemctl cat claude-app sẽ in secret ra cho bất kỳ user cục bộ nào.
  • Không commit key. .gitignore chỉ giữ một file mới nằm ngoài commit và không làm gì với file đã được commit, vì git history vẫn giữ mọi thứ đã được đưa vào đó.
  • Không nhúng key vào container image. Các giá trị ENV vẫn tồn tại trong cấu hình image, còn build arguments có thể nhìn thấy trong image history hoặc provenance metadata. Xóa file ở layer sau không xóa file khỏi layer trước. Thay vào đó, hãy truyền secret khi runtime bằng --env-file hoặc dùng file được mount.
  • Không xem process environment là dữ liệu riêng tư đối với root. sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n' sẽ in key ra. Bản thân lệnh đọc file cần sudo; shell input redirection chạy trước sudo và dùng quyền của account hiện tại. Mục tiêu là giữ secret khỏi mọi account khác trên máy, không phải khỏi root, vì root có thể đọc secret dù bạn làm cách nào.

Điểm cuối cùng xác định giới hạn bảo vệ của thiết kế này. File chỉ root đọc được bảo vệ key đã lưu, nhưng mọi code chạy bằng service account đều có thể đọc process environment, và các child process sẽ kế thừa environment đó. Đây là cách chứa secret không phù hợp khi process chạy code mà bạn không viết, vì bất kỳ thứ gì process có thể execute đều có thể đọc environment của chính nó. Giữ secret ngoài tầm với của AI agent đề cập đến trường hợp đó. Đây là một vấn đề khác và cần một cách xử lý khác.

Làm thế nào để thay key mà không gây downtime?

Triển khai key mới trước, rồi thu hồi key cũ sau cùng. Lần restart của một service đơn lẻ bên dưới sẽ làm gián đoạn service trong thời gian ngắn; để duy trì khả năng phục vụ liên tục, cần có instance khác xử lý request trong lúc restart.

  1. Tạo key mới trong Console, cùng workspace với key cũ.
  2. Ghi key mới vào /etc/claude-app/env bằng sudoedit.
  3. Chạy sudo systemctl restart claude-app.
  4. Xác nhận service đang trả lời request, rồi thu hồi key cũ trong Console.

EnvironmentFile được đọc khi unit khởi động, nên process đang chạy tiếp tục giữ giá trị được cấp lúc launch. systemctl daemon-reload đọc lại các unit file nhưng không chạm vào environment của process đang chạy, nên chỉ restart mới nạp key mới. Nếu thu hồi key ở bước 1 thay vì bước 4, bạn sẽ gây ra outage kéo dài cho đến bước 3.

Các cloud route được rotate tại phía provider. Một IAM user hỗ trợ đồng thời 2 access key đang hoạt động, nên hãy tạo key thứ hai, triển khai key đó, rồi xóa key thứ nhất. Google service account key cũng được rotate theo cách tương tự. Một Foundry resource có 2 key. Việc regenerate một key sẽ khiến giá trị cũ ngừng hoạt động ngay lập tức, nên hãy chuyển service sang key còn lại trước khi regenerate key mà service đang dùng. Entra token và federated Anthropic token không cần rotate token thủ công. Đây là lý do thuyết phục nhất để dùng chúng khi có thể.

Trong lúc đang ở Console, hãy đặt spend limit cho workspace. Key bị lộ trước hết sẽ gây tốn kém, và giới hạn số tiền agent trên VPS có thể chi hướng dẫn chi tiết các control.

Tại sao client của tôi trả về 401 hoặc 403?

401 với authentication_error trên direct API. Key sai, đã bị thu hồi hoặc hết hạn. Hạn hết là trường hợp dễ bị bỏ sót nhất vì code không thay đổi và request vẫn hoạt động vào hôm qua. Kiểm tra cột hết hạn của key trong Console hoặc đọc expires_at từ Admin API; giá trị này là null đối với key không có thời hạn. Personal key cũng ngừng hoạt động khi chủ sở hữu rời organization.

SDK bỏ qua cấu hình federation và dùng key thay thế. ANTHROPIC_API_KEY và ANTHROPIC_AUTH_TOKEN đứng trước federation trong thứ tự ưu tiên credential, nên một trong hai sẽ che khuất federation. Trường hợp dễ nhầm là một biến được export với chuỗi rỗng vẫn chiếm vị trí của nó, vì vậy ANTHROPIC_API_KEY="" khiến SDK authenticate bằng key rỗng thay vì chuyển sang cơ chế dự phòng. Dùng unset ANTHROPIC_API_KEY.

401 với thông báo chỉ chứa Authentication failed trên federation. Thông báo này được cố ý giữ giống hệt nhau cho mọi nguyên nhân có thể xảy ra, để caller không thể dò cấu hình rule bằng cách đọc nội dung lỗi. Lý do thực tế được ghi trên trang authentication history trong Console. Hãy bắt đầu từ đó thay vì đoán về JWT.

403 trên Foundry. Token đã authenticate thành công nhưng Azure account của bạn thiếu role cho phép thực hiện call. Gán một Azure RBAC role như Foundry User (trước đây là Azure AI User) hoặc Cognitive Services User cho identity thực hiện request.

Bất kỳ lỗi nào trên Bedrock. Với xác thực SigV4, trước tiên hãy chạy aws sts get-caller-identity bằng service user. Lệnh này cho biết máy có AWS credential có thể sử dụng hay không, từ đó phân biệt vấn đề credential với vấn đề quyền truy cập model hoặc sai region. Tính đến ngày 29 October 2026, AWS cho phép truy cập nhiều model ngay lần sử dụng đầu tiên tại các commercial region nếu có các quyền AWS Marketplace cần thiết, nhưng một số model yêu cầu cấp quyền riêng ở cấp account. Anthropic model được gọi qua route InvokeModel cần một use case form cho mỗi account (hoặc chỉ một lần cho toàn bộ AWS Organization, dù các opt-in region vẫn cần khai báo lại) trước khi sử dụng; cho đến khi form được duyệt, call sẽ trả về AccessDeniedException. AWS ghi rõ form này không áp dụng cho endpoint bedrock-mantle. Lần đầu gọi một model trong một account cũng khiến Bedrock bắt đầu subscription AWS Marketplace ở background; subscription đó cần một identity có các quyền aws-marketplace:Subscribe, aws-marketplace:Unsubscribe và aws-marketplace:ViewSubscriptions. Thiếu các quyền này không nhất thiết khiến call đầu tiên fail: AWS ghi rõ call có thể thành công trong tối đa 15 phút trong khi subscription đang được thiết lập; khi subscription fail, các call sau sẽ trả về cùng AccessDeniedException. Nếu một service hoạt động trong vài phút đầu rồi bắt đầu fail, hãy kiểm tra nguyên nhân này thay vì credential. Sau khi bạn cấp quyền, AWS cho phép tối đa 2 phút để subscription hoàn tất. Model không được cung cấp tại region bạn gọi sẽ fail dù credential hợp lệ đến đâu.

FAQ

Tôi có cần Anthropic API key để dùng Claude trên Bedrock hoặc Vertex không?

Không. Trên Amazon Bedrock, SDK ký request bằng AWS credentials sử dụng SigV4 hoặc gửi Bedrock API key, còn trên Google Cloud, SDK gửi Google access token được lấy thông qua Application Default Credentials. Cả hai thiết lập đều không có secret do Anthropic cấp, và usage được tính vào cloud account thay vì Anthropic. Đây cũng là lý do một Anthropic key để lại trong ANTHROPIC_API_KEY là mối nguy trên các host đó: một client generic trỏ đến cloud endpoint sẽ vẫn gửi key đó đến endpoint.

Claude có sẵn trên Azure không?

Có, thông qua Microsoft Foundry, trước đây có tên là Azure AI Foundry. Bạn tạo một Foundry resource, deploy Claude model vào đó, rồi gọi https://{resource}.services.ai.azure.com/anthropic/v1/messages bằng Azure-issued key trong header api-key hoặc Microsoft Entra bearer token. Usage được tính qua Azure Marketplace theo Claude Consumption Units. Trường model trong request body phải chứa deployment name của bạn. Tên này chỉ trùng với model identifier nếu bạn giữ tên mặc định khi tạo deployment; sau đó không thể đổi tên.

Tôi nên lưu Claude API key ở đâu trên Linux server?

Trong một file thuộc sở hữu của root, có mode 600, được load thông qua EnvironmentFile= trong systemd unit. systemd đọc file đó dưới quyền root trước khi chuyển sang User= của unit, nên service account không cần quyền truy cập file. Đừng lưu key trong repository, trong chính unit file (file này có thể được mọi người đọc và được in ra bởi systemctl cat), hoặc trong cấu hình container image, các layer và build metadata.

Vì sao Claude API request của tôi bắt đầu trả về 401 dù không có gì thay đổi?

Một key đã đến thời điểm hết hạn được chọn khi tạo sẽ trả về 401. Thời hạn được đặt lúc tạo key, không thể chỉnh sửa sau đó, và key có thời gian sống ngắn sẽ hết hạn mà không có email cảnh báo. Key đã hết hạn không thể kích hoạt lại. Hãy tạo key thay thế, ghi key đó vào environment file, restart service rồi revoke key cũ. Nếu key chắc chắn vẫn còn hạn, hãy kiểm tra xem một credential cũ có đang override nó không: ANTHROPIC_API_KEY được đặt thành chuỗi rỗng vẫn được ưu tiên hơn federation và profile sources bên dưới.

Bài viết này có hữu ích không?

#claude#api#authentication#bedrock#vertex#secrets-management