Xác thực Claude API: key, Bedrock, Vertex, Foundry

Bốn cách 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. Có 4 lựa chọn, và chúng không phải là các biến thể của cùng một cơ chế. Anthropic API trực tiếp gửi một static key trong header x-api-key. Amazon Bedrock ký mọi request bằng AWS credential, và trong mô hình này không có Anthropic key nào tồn tại. Google Cloud gửi một Google access token có thời hạn ngắn. Microsoft Foundry nhận một key do Azure cấp hoặc một Microsoft Entra token.

Hướng dẫn này dành cho việc tích hợp SDK (software development kit) vào một service đang 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 vào Bedrock hoặc Vertex. Nếu service chưa tồn tại, trước hết hãy tạo service 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.

Toàn bộ nội dung dưới đây đã được đối chiếu với tài liệu platform của Anthropic vào tháng 8 năm 2026. 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 từng provider thay vì in các giá trị có thể nhanh chóng lỗi thời.

Cách 1: API key của Anthropic

Đây là cách trực tiếp và là cách duy nhất Anthropic cấp secret. Request được gửi đến endpoint Messages trên API host của Anthropic, và mỗi request đều có 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 cùng 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ự thêm header này cho bạn.

Việc khởi tạo client là ngắn nhất trong 4 cách, vì không có gì cần tự cấu hình. Mọi SDK chính thức 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 string là công việc có thể tránh.

Bạn tạo key trong Console và chọn thời hạn ngay khi tạo: preset 3 giờ, 1 ngày, 7 ngày hoặc 30 ngày, thời hạn tùy chỉnh, hoặc Never. Thời hạn được cố định khi tạo và không thể thay đổi về sau. Anthropic gửi email cho người tạo key trước khi key dài hạn hết hạn, nhưng key có thời hạn ngắn sẽ hết hạn mà 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, vì vậy 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 tổ chức Anthropic của bạn. Workspace giới hạn một key vào 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. Xem cách so sánh giá API theo token với gói subscription để biết cách tính chi phí đó.

Có thêm một lựa chọn phù hợp với phần này vì nó loại bỏ hoàn toàn secret tĩnh. 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 ngắn hạn tại POST /v1/oauth/token; SDK sẽ refresh token đó trước khi hết hạn. Không có string 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 nền tảng đó đã có sẵn 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à lựa chọn thực tế; phần còn lại của hướng dẫn này cũng giả định như vậy.

Route 2: AWS credentials trên Amazon Bedrock

Trên Bedrock, bạn không cần giữ Anthropic key nào. SDK ký từng HTTP request bằng AWS Signature Version 4 (SigV4) sử dụng AWS credentials thông thường, rồi AWS quyết định identity đó có được phép gọi 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à credentials của bạn ánh xạ tới. Hãy chạy lệnh này trước mọi thao tác khác. Nếu lệnh thất bại, lệnh gọi Claude cũng sẽ thất bại, vì SDK duyệt cùng một chuỗi: tham số của constructor trước, sau đó là các biến môi trường AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN và AWS_REGION, rồi đến AWS config file và các nguồn còn lại trong standard chain (SSO, assumed role, ECS task role, instance metadata service).

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

from anthropic import AnthropicBedrock

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

Region không còn chỉ là thông tin trang trí. Bedrock endpoint được phân tách theo region, quyền truy cập model được cấp theo từng region trong AWS console, và region là một phần của SigV4 signature. Vì vậy, signature được tính cho một region sẽ bị region khác từ chối. Hãy đặt AWS_REGION một cách rõ ràng trong service environment. Anthropic ghi rõ rằng client AnthropicBedrock đọc AWS_REGION và dùng us-east-1 nếu biến này chưa được đặt, đồng thời không đọc ~/.aws/config để xác định region. Đây là lý do AWS CLI có thể liệt kê thành công các Claude model trên cùng một máy nơi Python process của bạn thất bại: CLI đọc config file, 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 một IAM user's long-lived access key pair nằm trên máy, có cùng loại rủi ro như 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 sử dụng temporary credentials mà STS trả về. Bedrock cũng chấp nhận bearer token qua AWS_BEARER_TOKEN_BEDROCK. Tài liệu của AWS nêu thời hạn tối đa là 12 giờ và mô tả đây là phương án ít được ưu tiên nhất.

Chi phí được tính vào AWS account của bạn thay vì Anthropic. Đây thường là lý do chính để sử dụng Bedrock. Regional endpoint có mức phí cao hơn 10% so với global endpoint, theo tài liệu được cập nhật vào tháng 8 năm 2026. Có một lỗi Bedrock bạn cần nhận diện vì trông giống lỗi permission 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. Đây là lỗi model routing, nên thay đổi credential sẽ không khắc phục được.

Lộ trình 3: Google credentials trên Vertex AI

Google Cloud sử dụng Application Default Credentials (ADC), tức 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, đây là công cụ không phù hợp vì credential được lưu thuộc về một người dùng cụ thể và sẽ mất hiệu lực khi tài khoản của người đó bị xóa. Bên ngoài Google Cloud cũng không có metadata server, nên ADC sẽ chuyển sang GOOGLE_APPLICATION_CREDENTIALS trỏ đến file service account key. File JSON đó là secret có thời hạn dài và phải được xử lý đúng như phần hướng dẫn sau đây. Bên trong Google Cloud, hãy gắn service account vào VM. Khi đó không có file nào cần bảo vệ.

from anthropic import AnthropicVertex

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

Có 2 điểm thay đổi khi bạn bỏ SDK và gọi raw HTTP. Model identifier được chuyển khỏi request body vào URL path, còn anthropic_version được chuyển khỏi header vào body, tại đó nó phải có giá trị vertex-2023-10-16. Credential là một Google access token thông thường.

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ố riêng trong request. global định tuyến động để tối ưu khả năng sẵn sàng, us và eu là các identifier multi-region, còn tên như us-east5 cố định một region duy nhất. Theo tài liệu được cập nhật vào August 2026, endpoint multi-region và regional có chi phí cao hơn global 10%. Billing được tính qua Google Cloud project, nên quota và hóa đơn do Google quản lý.

Route 4: Microsoft Foundry là route Azure

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

Có 2 loại credential có thể dùng. Loại 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. Loại thứ hai là Microsoft Entra token. Đây là lựa chọn tốt hơn trên server vì Azure role-based access control sẽ kiểm soát 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 deployment name, không phải model identifier. Theo mặc định, 2 giá trị này giống nhau. Chúng không còn giống nhau 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 hoàn toàn đúng. Python và TypeScript SDK đọc ANTHROPIC_FOUNDRY_API_KEY và ANTHROPIC_FOUNDRY_RESOURCE từ environment. Không phải SDK nào cũng hỗ trợ Foundry: theo tài liệu vào tháng 8 năm 2026, các SDK được hỗ trợ gồm C#, Java, PHP, Python và TypeScript. Go và Ruby SDK cần dùng generic client trỏ đến Foundry base URL.

Cách workaround này có một điểm dễ gây lỗi. Nếu ANTHROPIC_API_KEY vẫn được set trong environment, generic client sẽ đọc biến đó và gửi Anthropic key của bạn đến Microsoft endpoint. Hãy unset biến này hoặc tắt environment defaults trên client. Entra token hết hạn sau khoảng 1 giờ, vì vậy process chạy lâu phải refresh token thay vì lấy một token duy nhất khi khởi động.

Tuổi thọ của credential trên server là bao lâu?

[
  {
    "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 bearer token",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token",
    "max_lifetime_hours": 1
  },
  {
    "label": "Federated Anthropic token",
    "max_lifetime_hours": 1
  }
]

Đây là các giới hạn tối đa và giá trị mặc định do từng provider công bố, được ghi nhận vào tháng 8 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ộ còn hoạt động trong bao lâu, trong khi bạn vẫn đang xác định rằng nó đã bị lộ. Các token có thời hạn ngắn ở cuối biểu đồ có thời hạn 1 giờ mỗi token. SDK tự refresh các token này, nên thời hạn ngắn không làm tăng chi phí vận hành. Một role được assume có thời hạn 12 giờ. 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.

Nơi lưu credential trên VPS

Đặt secret trong một file mà chỉ root có thể đọc, rồi để systemd truyền secret đó cho process. Cách này không phụ thuộc vào phiên bản SDK, nên đáng thực hiện 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 KEY=value thuần túy. Không có export, dấu ngoặc kép hay 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 cần quyền đọc file. File thuộc sở hữu của root và có mode 600 là đủ. Vì vậy, lệnh install ở trên đặt quyền theo cách đó. Khởi động service bằng sudo systemctl enable --now claude-app, sau đó dùng systemctl status claude-app để xác nhận unit đã đạt trạng thái active (running) thay vì liên tục restart.

Có 4 việc cần tránh. Mỗi việc đề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ó thể được mọi user đọc, nên systemctl cat claude-app sẽ in secret cho bất kỳ user local nào.
• Không commit file này. .gitignore chỉ loại file mới khỏi commit và không xử lý file đã được commit, vì git history vẫn giữ mọi dữ liệu đã được đưa vào.
• Không đưa secret vào container image. Các dòng ENV và giá trị --build-arg được ghi vào các image layer, còn docker history --no-trunc sẽ in chúng ra. Xóa file trong layer sau không loại bỏ file khỏi layer trước đó. Thay vào đó, truyền secret lúc runtime bằng --env-file hoặc dùng file được mount.
• Không xem process environment là riêng tư đối với root. sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ sẽ in key ra. 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 vẫn 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 của thiết kế này. Environment variable là nơi chứa secret phù hợp khi chỉ service và root có thể đọc nó. Đây là lựa chọn sai khi process chạy code mà bạn không viết, vì bất kỳ code nào process có thể execute cũng có thể đọc environment của chính process đó. Giữ secret ngoài tầm với của AI agent trình bày trường hợp này. Đây là một bài toán khác và cần cách xử lý khác.

Làm thế nào để rotate key mà không downtime?

Rotate theo hướng tiến, rồi revoke key cũ sau cùng.

1. Tạo key mới trong Console, tại 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 revoke key cũ trong Console.

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

Ba route còn lại rotate tại provider. Một IAM user hỗ trợ đồng thời 2 access key đang active, nên hãy tạo key thứ hai, deploy key đó, rồi xóa key thứ nhất. Google service account key cũng rotate theo cách tương tự. Foundry key được regenerate trong portal, thao tác này lập tức invalidate key cũ, vì vậy hãy ghi giá trị mới trước khi click. Entra token và federated Anthropic token hoàn toàn không cần rotate. Đâ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 trình bày các control liên quan.

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

401 kèm authentication_error trên API trực tiếp. Key không đúng, đã bị thu hồi hoặc đã hết hạn. Hết hạn là trường hợp dễ bị bỏ sót nhất vì code không thay đổi và request vẫn chạy hôm qua. Kiểm tra cột thời hạn của key trong Console hoặc đọc expires_at từ Admin API. Trường này là null với các key không có thời hạn.

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 cấu hình đó. 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 xác thực bằng key rỗng thay vì chuyển sang cơ chế tiếp theo. Dùng unset ANTHROPIC_API_KEY.

401 với thông báo ngắn Authentication failed trên federation. Thông báo này được cố ý giữ giống nhau cho mọi nguyên nhân có thể xảy ra. Nhờ đó, caller không thể dò cấu hình rule bằng cách đọc nội dung lỗi. Nguyên nhân thực tế được ghi trên trang lịch sử xác thực trong Console. Hãy kiểm tra tại đó trước khi đoán nguyên nhân từ JWT.

403 trên Foundry. Token đã xác thực thành công nhưng tài khoản Azure 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.

Mọi lỗi trên Bedrock. Trước tiên, chạy aws sts get-caller-identity bằng service user. Lệnh này cho biết máy có credential AWS dùng được hay không. Nhờ đó, bạn có thể phân biệt lỗi credential với lỗi quyền truy cập model hoặc lỗi khác region. Quyền truy cập model được cấp riêng cho từng region trong AWS console. Bạn có thể dễ dàng bật quyền ở một region nhưng lại gọi sang region khác.

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ý từng request bằng AWS credentials sử dụng SigV4. Trên Google Cloud, SDK gửi Google access token được lấy thông qua Application Default Credentials. Cả hai cấu hình đều không có secret do Anthropic cấp. Chi phí sử dụng được tính vào cloud account thay vì Anthropic. Đây cũng là lý do một Anthropic key còn sót trong ANTHROPIC_API_KEY là rủi ro trên các host đó: một client generic trỏ đến cloud endpoint sẽ vẫn gửi key này đến đó.

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 một 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 bằng Microsoft Entra bearer token. Chi phí sử dụng đượ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 cho đến khi bạn đổi tên deployment.

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

Lưu trong một file do root sở hữu, với mode 600, rồi load file thông qua EnvironmentFile= trong systemd unit. systemd đọc file đó vớ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. Không lưu key trong repository, trong chính unit file vì file này có thể được mọi người đọc và được in ra bởi systemctl cat, hoặc trong các container image layer vì docker history --no-trunc sẽ in lại mọi giá trị được thiết lập bằng ENV hoặc --build-arg.

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

Nguyên nhân thường gặp nhất là key đã đến thời điểm hết hạn được chọn khi key được tạo. Thời hạn được đặt lúc tạo key và không thể chỉnh sửa sau đó. Short-lived key 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ũ sau đó. Nếu key chắc chắn vẫn còn hiệu lực, hãy kiểm tra xem credential cũ có đang ghi đè lên key đó không: ANTHROPIC_API_KEY được đặt thành chuỗi rỗng vẫn có độ ưu tiên cao hơn mọi credential source khác.