Claude API: klucz, Bedrock, Vertex i Microsoft Foundry
Jak uwierzytelnić klienta Claude API na VPS przez klucz Anthropic, AWS IAM, Google ADC lub Microsoft Entra oraz bezpiecznie przechowywać dane serwera.
Ścieżki uwierzytelniania Claude API
Uwierzytelnianie w Claude API sprowadza się do jednej decyzji: jakiego poświadczenia użyje klient w komunikacji sieciowej. Anthropic udostępnia bezpośrednie Claude API oraz pięć platform chmurowych: Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (zarządzane przez Google), Claude Models on Google Cloud (zarządzane przez Anthropic) oraz Microsoft Foundry. Bezpośrednie API Anthropic akceptuje klucz API lub krótkotrwały token w nagłówku Authorization: Bearer, a w ramach kompatybilności wstecznej nadal obsługuje klucze API w nagłówku x-api-key. Amazon Bedrock wspiera podpisywanie żądań AWS oraz klucze Bedrock API; w tej konfiguracji klucz Anthropic nie występuje. Google Cloud przesyła krótkotrwały token dostępu Google. Microsoft Foundry wymaga klucza wydanego przez Azure lub tokenu Microsoft Entra. Poniższe cztery sekcje opisują te konfiguracje poświadczeń, uwzględniając oferty AWS i Google Cloud zarządzane przez Anthropic wraz z ich odpowiednikami chmurowymi.
Ten przewodnik dotyczy integracji SDK (software development kit) z usługą działającą na serwerze Linux. Jeśli konfigurujesz narzędzie wiersza poleceń Claude Code, zmienne oraz przebieg procesu są inne: zobacz wskazywanie Claude Code na Bedrock lub Vertex. Jeśli usługa jeszcze nie istnieje, zbuduj ją najpierw zgodnie z pierwsza aplikacja Claude API na VPS i wróć tutaj po konfigurację poświadczeń.
Wszystkie poniższe informacje zostały zweryfikowane z dokumentacją platformy Anthropic w sierpniu 2026 r. i ponownie sprawdzone z dokumentacją każdego dostawcy w dniu 16 października 2026 r.; szczegóły dostępu do modeli Bedrock sprawdzono ponownie w dokumentacji AWS w dniu 19 października 2026 r. Strony Anthropic dotyczące wszystkich czterech ścieżek, kluczy API oraz wersji API sprawdzono ponownie 27 października 2026 r. Strony Anthropic dotyczące Microsoft Foundry, obu punktów końcowych Bedrock, ścieżki zarządzanej przez Google, Claude Platform on AWS, uwierzytelniania, Workload Identity Federation oraz wersji API sprawdzono ponownie 10 listopada 2026 r., wraz z dziennikiem zmian Ruby SDK. Identyfikatory modeli, ceny, wersje SDK oraz struktury punktów końcowych ulegają zmianom, dlatego niniejszy przewodnik odsyła do stron dostawców zamiast podawać wartości, które mogą stać się nieaktualne.
Trasa 1: klucz API Anthropic
To bezpośrednia ścieżka i jedyna, na której Anthropic wydaje sekret. Żądania trafiają do endpointu Messages na hoście API Anthropic, a każde żądanie zawiera trzy nagłówki.
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"}]}'Zastąp MODEL_ID aktualnym identyfikatorem z przeglądu modeli Anthropic. Prawidłowa odpowiedź jest obiektem JSON zawierającym tablicę content oraz obiekt usage. Nieprawidłowy lub wygasły klucz powoduje odpowiedź HTTP 401 z wartością authentication_error. Brak nagłówka anthropic-version jest osobnym błędem, ponieważ ten nagłówek jest wymagany w każdym żądaniu; SDK ustawiają go automatycznie. Według dokumentacji Anthropic z października 2026 główną metodą przesyłania klucza jest Authorization: Bearer, a x-api-key jest oznaczony jako starszy mechanizm. Oba warianty są jednak akceptowane, więc powyższe polecenie nadal działa. Aktualne główne wersje SDK przesyłają klucz również jako Authorization: Bearer, dlatego proxy lub gateway odczytujący X-Api-Key wymaga zmiany po aktualizacji. Wersja 2023-06-01 użyta w poleceniu jest nadal akceptowana. Najnowsza wersja API Anthropic to 2026-10-21. Te wersje SDK wysyłają ją domyślnie, a ona odrzuca kilka starszych parametrów żądania, takich jak temperature.
Tworzenie klienta jest najkrótszą z tych konfiguracji, ponieważ niczego nie trzeba konstruować. Każde oficjalne SDK samodzielnie odczytuje ANTHROPIC_API_KEY ze środowiska.
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)Warto przechowywać identyfikator modelu w środowisku obok klucza. Nazwy modeli zmieniają się zgodnie z harmonogramem, na który nie masz wpływu. Ponowne wdrażanie kodu tylko po to, aby zmienić jeden ciąg znaków, jest zbędną pracą.
Klucze tworzy się w Console, gdzie podczas tworzenia wybiera się czas wygaśnięcia: 3 hours, 1 day, 7 days lub 30 days, własny czas trwania albo Never, z uwzględnieniem maksymalnej polityki wygaśnięcia obowiązującej w organizacji. Czas wygaśnięcia jest ustalany podczas tworzenia i nie można go później zmienić. Anthropic wysyła twórcy klucza wiadomość e-mail przed wygaśnięciem klucza długoterminowego, ale klucz o krótkim czasie życia wygasa bez żadnego ostrzeżenia e-mail. Wygasły klucz zwraca 401 i nie można go ponownie aktywować, dlatego rozwiązaniem jest zawsze utworzenie nowego klucza.
W bezpośrednim API nie wybiera się regionu, a opłaty są naliczane bezpośrednio na rzecz organizacji Anthropic. Workspace ogranicza klucz do jednego projektu, co jest najprostszym sposobem ustalenia, ile wydaje pojedyncza usługa. Podczas tworzenia klucza serwera przypisz go do jego workspace: klucz osobisty lub klucz konta usługi, który nie jest przypisany do workspace, musi przesyłać nagłówek anthropic-workspace-id przy każdym żądaniu. W przeciwnym razie API zwraca 400 z wartością invalid_request_error. W przypadku usługi wybierz klucz konta usługi, ponieważ klucz osobisty przestaje działać po odejściu jego twórcy z organizacji. Informacje o obliczeniach stojących za tymi opłatami znajdują się w sekcji porównanie cen API za token z ceną subskrypcji.
Warto omówić jeszcze jedną opcję, ponieważ całkowicie eliminuje statyczny sekret. Workload Identity Federation pozwala wymienić token OpenID Connect (OIDC) od już zaufanego dostawcy tożsamości na krótkotrwały token Anthropic w POST /v1/oauth/token, a SDK odświeża ten token przed jego wygaśnięciem. Żaden ciąg sk-ant-api... nie jest nigdy tworzony ani kopiowany. To rozwiązanie pasuje do Kubernetes, GitHub Actions i maszyn wirtualnych w chmurze, które już mają tożsamość platformy. Zwykły VPS zazwyczaj nie ma takiego wystawcy, dlatego na takim hoście klucz API w pliku jest właściwym rozwiązaniem. W dalszej części tego przewodnika przyjęto właśnie taki model.
Ścieżka 2: Poświadczenia AWS w Amazon Bedrock
W usłudze Bedrock nie przechowuje się żadnego klucza Anthropic. Dzięki poświadczeniom AWS zestaw SDK podpisuje każde żądanie HTTP przy użyciu AWS Signature Version 4 (SigV4), a AWS decyduje, czy dany podmiot może wywołać model.
pip install -U "anthropic[bedrock]"
aws sts get-caller-identityaws sts get-caller-identity wyświetla numer konta oraz ARN (Amazon Resource Name) tożsamości, do której przypisane są poświadczenia. Uruchom to polecenie jako pierwsze podczas korzystania z SigV4. W przypadku SigV4 zestaw SDK rozpoznaje poświadczenia konstruktora, poświadczenia środowiskowe oraz standardowy łańcuch poświadczeń AWS; wybór regionu odbywa się oddzielnie. W kliencie AnthropicBedrock dla języka Python, klucz API Bedrock dostarczony jako api_key lub przez AWS_BEARER_TOKEN_BEDROCK spowoduje zgłoszenie ValueError, jeśli przekażesz również aws_access_key, aws_secret_key, aws_session_token lub aws_profile. Bez tych jawnych argumentów klucz wybiera uwierzytelnianie typu bearer zamiast łańcucha poświadczeń AWS. Klient TypeScript nadaje kluczowi API Bedrock wyższy priorytet niż jawnym poświadczeniom AWS. Polecenie STS nie testuje uwierzytelniania typu bearer.
Zmiany w konstrukcji klienta dotyczą klasy oraz jednego argumentu.
from anthropic import AnthropicBedrock
client = AnthropicBedrock(aws_region="us-east-1")AnthropicBedrock obsługuje integrację InvokeModel w Bedrock. Według stanu na październik 2026 r. firma Anthropic dokumentuje również usługę Claude in Amazon Bedrock, punkt końcowy Messages API pod adresem https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages dla modelu Claude Opus 4.7 i nowszych, dostępny przez klienta AnthropicBedrockMantle z tego samego pakietu. Obsługuje on poświadczenia AWS oraz tokeny bearer Bedrock; wymagania dotyczące dostępu do modelu różnią się między tymi dwoma punktami końcowymi, co wyjaśniono poniżej.
Zwróć uwagę na aktualizację w linii pip install -U. Od 27 października 2026 r. najnowszy zestaw SDK domyślnie wysyła wersję API 2026-10-21, również w ramach Bedrock. Anthropic dokumentuje, że identyfikatory modeli z wersją ARN wymienione dla Claude Opus 4.6 i wcześniejszych nie obsługują tej wersji w Bedrock i mogą zwracać błąd 400. Jeśli usługa wywołuje jeden z tych modeli, należy pozostawić SDK w używanej obecnie wersji i przypiąć ją (pin) lub najpierw przenieść usługę na model Claude 4.7 lub nowszy.
Region przestaje być tutaj tylko dekoracją. Punkty końcowe Bedrock są przypisane do regionów, oferowane modele Claude różnią się w zależności od regionu, a region jest częścią podpisu SigV4, więc podpis obliczony dla jednego regionu jest odrzucany przez inny. Ustaw AWS_REGION jawnie w środowisku usługi, ponieważ zestawy SDK nie są zgodne co do zachowania w przypadku pominięcia tego parametru. Zgodnie z dokumentacją z października 2026 r., klient AnthropicBedrock dla języka Python odczytuje AWS_REGION lub AWS_DEFAULT_REGION, następnie region sesji boto3 lub profilu AWS (w tym ~/.aws/config) i zgłasza ValueError, jeśli żaden z nich nie zostanie rozpoznany. Klient TypeScript odczytuje AWS_REGION, w przypadku jego braku wraca do us-east-1 i nie odczytuje ~/.aws/config w celu ustalenia regionu. Dlatego AWS CLI może z powodzeniem wyświetlić listę modeli Claude na tej samej maszynie, na której proces Node wywołuje niewłaściwy region: CLI odczytało plik konfiguracyjny, a klient nie.
Na instancji EC2 przypisuje się rolę IAM (identity and access management) i żaden sekret nie trafia na dysk, ponieważ usługa metadanych instancji przekazuje zestawowi SDK tymczasowe poświadczenia. VPS poza AWS nie posiada ani roli instancji, ani usługi metadanych. Wybierasz wtedy między długoterminową parą kluczy dostępu użytkownika IAM przechowywaną na maszynie, która jest tym samym rodzajem sekretu co klucz Anthropic, a federacją: uwierzytelnieniem u dostawcy tożsamości, wywołaniem AWS STS (security token service) i użyciem zwróconych tymczasowych poświadczeń. Bedrock akceptuje również klucze API Bedrock, które są tokenami bearer przekazywanymi przez AWS_BEARER_TOKEN_BEDROCK; AWS dokumentuje dwa ich rodzaje. Klucz krótkoterminowy jest ważny do 12 godzin lub przez czas trwania sesji, która go wygenerowała (jeśli jest krótsza), dziedziczy uprawnienia tożsamości IAM, która go utworzyła, i jest rodzajem klucza zalecanym przez AWS do środowisk produkcyjnych. Klucz długoterminowy jest ważny do wybranej daty wygaśnięcia (na przykład 30 lub 90 dni przy użyciu --credential-age-days) lub nie wygasa, jeśli ten parametr API zostanie pominięty; konsola tworzy dla niego użytkownika IAM, a AWS zaleca go tylko do celów testowych. Klucz długoterminowy działa tylko w regionie, w którym został wygenerowany; użycie go w innym regionie zwraca Credential should be scoped to a valid region.
Rachunek trafia na konto AWS, a nie do Anthropic, co zazwyczaj jest głównym powodem korzystania z tego rozwiązania. Regionalne punkty końcowe wiążą się z 10% dopłatą w stosunku do globalnego punktu końcowego, zgodnie z dokumentacją z października 2026 r. Claude Platform on AWS to oddzielny produkt: Anthropic go obsługuje, AWS rozlicza go przez AWS Marketplace, a uwierzytelnianie odbywa się za pomocą SigV4 lub klucza API wygenerowanego w konsoli AWS (klucze z konsoli Claude tam nie działają), poprzez klienta AnthropicAWS, którego Anthropic oznacza jako beta. Warto rozpoznać jeden błąd Bedrock, ponieważ wygląda jak problem z uprawnieniami, a nim nie jest: 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.. Jest to routing modelu i żadna zmiana poświadczeń tego nie naprawi.
Trasa 3: dane uwierzytelniające Google w Vertex AI
Dokumentacja Anthropic nazywa obecnie tę trasę Claude Models on Google Cloud (Google managed). Google obsługuje ją w ramach Agent Platform, czyli nowej nazwy usługi rozwijanej wcześniej jako Vertex AI. Host aiplatform.googleapis.com, dodatkowy element anthropic[vertex] oraz klasa AnthropicVertex pokazane poniżej pozostają bez zmian.
Google Cloud używa Application Default Credentials (ADC) — stałej kolejności wyszukiwania stosowanej przez biblioteki uwierzytelniania Google w celu znalezienia danych uwierzytelniających bez ich jawnego wskazywania. ADC najpierw sprawdza GOOGLE_APPLICATION_CREDENTIALS, następnie plik zapisany przez gcloud auth application-default login, a na końcu konto usługi przypisane przez serwer metadanych.
pip install -U "anthropic[vertex]"
gcloud auth application-default loginNa stacji roboczej to logowanie zapisuje $HOME/.config/gcloud/application_default_credentials.json i na tym można zakończyć konfigurację. Na serwerze należy unikać przechowywania danych uwierzytelniających użytkownika. Polecenie obsługuje również impersonację konta usługi. Poza Google Cloud nie ma serwera metadanych Google, dlatego należy użyć GOOGLE_APPLICATION_CREDENTIALS, aby wskazać ADC plik konfiguracji Workload Identity Federation albo plik klucza konta usługi. Plik JSON z kluczem konta usługi jest długoterminowym sekretem i wymaga dokładnie takiego postępowania, jak opisano w dalszej części tego przewodnika. W Google Cloud należy przypisać konto usługi do VM. W takim przypadku nie ma pliku wymagającego ochrony. Tożsamość znaleziona przez ADC musi mieć rolę IAM obejmującą uprawnienie aiplatform.endpoints.predict, na przykład Agent Platform User (roles/aiplatform.user).
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")Przejście z SDK do surowego HTTP zmienia dwie kwestie. Identyfikator modelu jest przenoszony z treści żądania do ścieżki URL, a anthropic_version jest przenoszone z nagłówka do treści. Według stanu na 27 October 2026 dokumentacja Anthropic dopuszcza tam zarówno vertex-2023-10-16, jak i nowszą wersję API 2026-10-21. Dane uwierzytelniające są zwykłym tokenem dostępu Google. W poniższym poleceniu gcloud auth print-access-token korzysta z logowania wykonanego przez CLI gcloud, a nie z ADC. Dlatego na komputerze, na którym wykonywane są testy, należy najpierw uruchomić gcloud auth login albo 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 jest jawnym argumentem. global kieruje ruch dynamicznie w celu zapewnienia dostępności, us i eu to identyfikatory wieloregionalne, a nazwa taka jak us-east5 przypina żądanie do jednego regionu. Według stanu na October 2026 Anthropic dokumentuje endpointy jednoregionowe wyłącznie dla Claude Sonnet 4.6 i wcześniejszych modeli. Nowsze modele używają endpointów globalnych albo wieloregionalnych. Zgodnie z dokumentacją z October 2026 endpointy wieloregionalne i regionalne kosztują 10% więcej niż globalne. Rozliczenia odbywają się za pośrednictwem projektu Google Cloud, dlatego limity i faktury obsługuje Google.
Według stanu na 27 October 2026 Anthropic dokumentuje również drugą ofertę Google Cloud, która ma inną strukturę żądania. W Claude Models on Google Cloud (Anthropic managed) Anthropic samodzielnie obsługuje API Claude pod adresem claude.googleapis.com, do którego uzyskuje się dostęp za pomocą klienta AnthropicGoogleCloud. Uwierzytelnianie nadal wykorzystuje dane uwierzytelniające Google Cloud, w tym ADC, ale żądanie przypomina żądanie do bezpośredniego API: model pozostaje w treści, a wersja jest przekazywana w nagłówku anthropic-version. Dostęp jest przyznawany za pomocą własnych ról IAM (roles/claude.user i powiązanych). Konfiguracja tworzy nową organizację Anthropic dla projektu, a użycie jest rozliczane za pośrednictwem Google Cloud Marketplace. Jeżeli adresy żądań zawierają aiplatform i kończą się na :rawPredict, używana jest trasa zarządzana przez Google opisana w tej sekcji.
Ścieżka 4: Microsoft Foundry to ścieżka Azure
Jeśli szukałeś Claude w Azure, to jest sekcja, której potrzebujesz; obsługiwana ścieżka istnieje. Claude działa w Microsoft Foundry (dawniej Azure AI Foundry), a rozliczenia odbywają się przez Azure Marketplace w jednostkach Claude Consumption Units. Należy utworzyć zasób Foundry, wdrożyć w nim model Claude i wywołać punkt końcowy hostowany w Azure pod adresem https://{resource}.services.ai.azure.com/anthropic/v1/*.
Działają dwa rodzaje poświadczeń. Pierwszym jest klucz wydany przez Azure, dostępny w zakładce Details wdrożenia w portalu Foundry, przesyłany w nagłówku api-key lub x-api-key. Drugim jest token Microsoft Entra, co stanowi lepszy wybór na serwerze, ponieważ kontrola dostępu oparta na rolach (RBAC) w Azure zarządza wtedy uprawnieniami do wywoływania punktu końcowego.
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"}]}'Pole model zawiera nazwę wdrożenia, a nie identyfikator modelu. Domyślnie obie wartości są zgodne, jednak przestają być takie w momencie nadania własnej nazwy wdrożeniu, co jest najczęstszą przyczyną błędu Deployment not found przy poprawnie sformułowanym żądaniu. SDK dla języków Python i TypeScript odczytują ANTHROPIC_FOUNDRY_API_KEY oraz ANTHROPIC_FOUNDRY_RESOURCE ze środowiska. Według stanu na 10 listopada 2026 r. wsparcie Foundry obejmuje wszystkie siedem oficjalnych SDK: C#, Go, Java, PHP, Python, Ruby i TypeScript. Go używa dedykowanego pakietu foundry (go get github.com/anthropics/anthropic-sdk-go/v2/foundry), a Ruby otrzymało dedykowane Anthropic::FoundryClient w wersji 2.5.0 gema, wydanej 4 listopada 2026 r. Przed tą wersją kod w Ruby musiał wskazywać ogólny klient na bazowy adres URL Foundry.
Wskazywanie ogólnego klienta na bazowy adres URL Foundry nadal wiąże się z ryzykiem, niezależnie od tego, czy jest to kod w Ruby napisany przed wersją 2.5.0, czy narzędzie CLI ant, które w przykładach Anthropic dla Foundry jest tak wywoływane. Jeśli nie przekażesz poświadczeń do ogólnego klienta jawnie, a w środowisku nadal ustawione są ANTHROPIC_API_KEY lub ANTHROPIC_AUTH_TOKEN, klient pobierze je i wyśle poświadczenia Anthropic do punktu końcowego Microsoft. Usuń zmienną lub przekaż klucz Foundry bądź token do klienta jawnie. W Ruby przejście na Anthropic::FoundryClient, które przyjmuje klucz Foundry lub dostawcę tokenów Entra, jest czystszym rozwiązaniem. Token dostępu Entra otrzymuje losowy domyślny czas życia od 60 do 90 minut, więc długo działający proces musi go odświeżać, zamiast pobierać go tylko przy starcie.
Jak długo ważne są poświadczenia na serwerze?
Dane, na których opiera się ten wykres
[
{
"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
}
]Są to limity oraz wartości domyślne opublikowane przez poszczególnych dostawców, odczytane w październiku 2026 roku, a nie wartości zmierzone. Mają one znaczenie z jednego powodu: określają, jak długo wyciekłe poświadczenie pozostaje aktywne, podczas gdy administrator wciąż ustala fakt wystąpienia wycieku. Sfederowany token Anthropic na dole wykresu jest domyślnie ważny do 1 godziny, przy czym czas ten jest ograniczony również przez dwukrotność pozostałego czasu ważności tokena dostawcy tożsamości. Token dostępu Microsoft Entra nie posiada jednej wartości domyślnej: Microsoft nadaje każdemu z nich losowy czas ważności od 60 do 90 minut (średnio 75), co na wykresie przedstawiono jako górną granicę 1.5 godzin. Wartość domyślna różni się w zależności od klienta, zasobu oraz tego, czy w dzierżawie włączono Conditional Access. Gdy zarówno klient, jak i zasób obsługują Continuous Access Evaluation, Entra może wydłużyć czas ważności do 24–28 godzin i unieważnić token niemal w czasie rzeczywistym w przypadku wystąpienia zdarzeń takich jak wyłączenie konta. Zasada okresu ważności tokena dzierżawy pozwala ustawić go w zakresie od 10 minut do 23:59:59. Zestawy SDK automatycznie odświeżają sfederowane tokeny Anthropic; w Foundry należy skonfigurować dostawcę tokenów Entra w celu odświeżania tokenów, zamiast przekazywania stałego ciągu znaków tokena. Reguła federacji może definiować własny czas ważności tokena w zakresie od jednej minuty do 24 godzin, a kreator obciążeń Connect w konsoli domyślnie ustawia 10 minut, dlatego należy sprawdzić regułę, zamiast zakładać wartość domyślną. Przyjęta rola oraz krótkoterminowy klucz API Bedrock mają czas ważności wynoszący 12 godziny. Długoterminowy klucz API Bedrock nie znajduje się na wykresie, ponieważ nie posiada stałego limitu: jest ważny do momentu wygaśnięcia wybranego podczas tworzenia lub nie wygasa wcale, jeśli CredentialAgeDays pominięto w wywołaniu API, dlatego AWS zaleca stosowanie go wyłącznie do celów testowych. Klucz utworzony z ustawieniem wstępnym 30 dni pozostaje ważny przez 720 godzin i jest to poświadczenie, które pozostaje w pliku na serwerze przez miesiąc.
Gdzie znajduje się poświadczenie na VPS
Sekret należy umieścić w pliku, który może odczytać wyłącznie root, i przekazać go procesowi za pośrednictwem systemd. Ta część nie zależy od wersji SDK, dlatego warto skonfigurować ją raz i poprawnie.
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/envPlik zawiera zwykłe wiersze KEY=value. Nie należy używać export, cudzysłowów ani składni powłoki, ponieważ systemd analizuje plik samodzielnie, zamiast przekazywać go do powłoki.
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 odczytuje EnvironmentFile= jako root, zanim przełączy się na User=claudeapp, dlatego konto usługi nie musi mieć uprawnień do odczytu pliku. Wystarczy tryb 600 i właściciel root. Z tego powodu polecenie install powyżej ustawia właśnie takie uprawnienia. Usługę należy uruchomić za pomocą sudo systemctl enable --now claude-app, a następnie potwierdzić za pomocą systemctl status claude-app, że jednostka osiągnęła stan active (running), zamiast ciągle się restartować.
Należy unikać czterech rzeczy. Każdy z poniższych powodów można samodzielnie zweryfikować:
- Nie należy zapisywać klucza za pomocą
Environment=wewnątrz pliku jednostki. Jednostka znajdująca się w/etc/systemd/systemjest dostępna do odczytu dla wszystkich, dlategosystemctl cat claude-appwyświetli sekret każdemu użytkownikowi lokalnemu. - Nie należy dodawać go do repozytorium.
.gitignorewyklucza nowy plik z commita, ale nie zmienia niczego w przypadku pliku, który został już zatwierdzony, ponieważ historia git zachowuje wszystko, co do niej trafiło. - Nie należy osadzać go w obrazie kontenera. Wartości
ENVpozostają w konfiguracji obrazu, a argumenty kompilacji są widoczne w historii obrazu lub metadanych pochodzenia. Usunięcie pliku w późniejszej warstwie nie usuwa go z wcześniejszej warstwy. Zamiast tego należy przekazywać sekrety w czasie uruchamiania za pomocą--env-filelub zamontowanego pliku. - Nie należy zakładać, że środowisko procesu jest prywatne względem root.
sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n'ponownie wyświetla klucz. Samo polecenie odczytujące plik wymagasudo; przekierowanie wejścia w powłoce jest wykonywane przedsudoi korzysta z uprawnień bieżącego konta. Celem jest ukrycie sekretu przed wszystkimi pozostałymi kontami w systemie, a nie przed root, który może go odczytać niezależnie od zastosowanego rozwiązania.
Ostatnia kwestia wyznacza granice ochrony zapewnianej przez ten mechanizm. Plik dostępny wyłącznie dla root chroni zapisany klucz, ale każdy kod uruchomiony jako konto usługi może odczytać środowisko procesu, a procesy potomne dziedziczą to środowisko. Jest to niewłaściwe rozwiązanie, gdy proces wykonuje kod, którego nie napisano samodzielnie, ponieważ wszystko, co proces może uruchomić, może również odczytać jego środowisko. Przypadek ten opisano w Ochrona sekretów przed dostępem agenta AI. Jest to inny problem, który wymaga innego rozwiązania.
Jak obrócić klucz bez przestoju?
Najpierw wdroż nowy klucz, a stary unieważnij na końcu. Poniższy restart pojedynczej usługi powoduje krótką przerwę w jej działaniu. Nieprzerwana dostępność wymaga drugiej instancji, która będzie obsługiwać żądania podczas restartu.
- Utwórz nowy klucz w Console, w tym samym workspace co stary klucz.
- Zapisz go w
/etc/claude-app/envza pomocąsudoedit. - Uruchom
sudo systemctl restart claude-app. - Potwierdź, że usługa odpowiada na żądania, a następnie unieważnij stary klucz w Console.
EnvironmentFile jest odczytywane podczas uruchamiania jednostki, dlatego działający proces zachowuje wartość przekazaną mu przy starcie. systemctl daemon-reload ponownie odczytuje pliki jednostek, ale nie zmienia środowiska działającego procesu, więc nowy klucz zostanie użyty dopiero po restarcie. Unieważnienie klucza w kroku 1 zamiast w kroku 4 spowoduje przestój trwający aż do kroku 3.
Rotacja kluczy dla tras chmurowych odbywa się po stronie dostawcy. Użytkownik IAM może mieć jednocześnie dwa aktywne klucze dostępu, dlatego należy utworzyć drugi klucz, wdrożyć go, a następnie usunąć pierwszy. Klucz konta usługi Google obraca się w ten sam sposób. Zasób Foundry ma dwa klucze. Wygenerowanie nowej wartości jednego z nich natychmiast unieważnia starą wartość. Przed ponownym wygenerowaniem klucza używanego przez usługę należy przełączyć usługę na drugi klucz. Tokeny Entra i federacyjne tokeny Anthropic nie wymagają ręcznej rotacji. Jest to najważniejszy argument za używaniem ich wszędzie tam, gdzie jest to możliwe.
Przy okazji ustaw limit wydatków dla workspace w Console. Ujawniony klucz przede wszystkim generuje koszty. Ograniczanie wydatków agenta działającego na VPS opisuje dostępne mechanizmy kontroli.
Dlaczego klient zwraca 401 lub 403?
401 z authentication_error w bezpośrednim API. Klucz jest nieprawidłowy, unieważniony albo utracił ważność. Wygaśnięcie ważności jest często pomijane, ponieważ kod się nie zmienił, a żądanie działało poprzedniego dnia. Sprawdź kolumnę wygaśnięcia ważności klucza w Console albo odczytaj expires_at z Admin API. Dla kluczy bez terminu wygaśnięcia ma on wartość null. Klucz osobisty również przestaje działać, gdy jego właściciel opuszcza organizację.
SDK pomija konfigurację federacji i używa klucza. ANTHROPIC_API_KEY i ANTHROPIC_AUTH_TOKEN mają wyższy priorytet niż federacja w kolejności wyboru poświadczeń, więc każdy z nich ją przesłania. Istotny szczegół: zmienna wyeksportowana jako pusty ciąg nadal zajmuje swoje miejsce. W efekcie ANTHROPIC_API_KEY="" powoduje uwierzytelnianie SDK pustym kluczem zamiast przejścia do kolejnej metody. Użyj unset ANTHROPIC_API_KEY.
401 z samym komunikatem Authentication failed w federacji. Ten komunikat jest celowo identyczny dla każdej możliwej przyczyny, aby wywołujący nie mógł rozpoznawać konfiguracji reguł na podstawie treści błędu. Rzeczywista przyczyna jest zapisywana na stronie historii uwierzytelniania w Console. Najpierw sprawdź tę stronę, zamiast zgadywać na podstawie JWT.
403 w Foundry. Token został uwierzytelniony, ale konto Azure nie ma roli zezwalającej na wykonanie wywołania. Przypisz tożsamości wykonującej żądanie rolę Azure RBAC, taką jak Foundry User (wcześniej Azure AI User) albo Cognitive Services User.
Dowolny błąd w Bedrock. W przypadku uwierzytelniania SigV4 najpierw uruchom aws sts get-caller-identity jako użytkownik usługi. Polecenie sprawdza, czy host ma w ogóle użyteczne poświadczenia AWS. Pozwala to odróżnić problem z poświadczeniami od problemu z dostępem do modelu lub niezgodności regionu. Od 29 October 2026 AWS włącza dostęp do wielu modeli przy pierwszym użyciu w regionach komercyjnych, jeśli są wymagane uprawnienia AWS Marketplace. Niektóre modele wymagają jednak osobnego dostępu na poziomie konta. Modele Anthropic wywoływane za pośrednictwem trasy InvokeModel wymagają najpierw jednorazowego formularza zastosowania dla każdego konta albo jednego formularza dla całej AWS Organization. W regionach wymagających aktywacji należy wypełnić formularz ponownie. Do czasu jego zatwierdzenia wywołanie zwraca AccessDeniedException. AWS dokumentuje, że formularz nie dotyczy endpointu bedrock-mantle. Pierwsze wywołanie modelu na koncie powoduje również rozpoczęcie przez Bedrock subskrypcji AWS Marketplace w tle. Subskrypcja wymaga tożsamości z uprawnieniami aws-marketplace:Subscribe, aws-marketplace:Unsubscribe i aws-marketplace:ViewSubscriptions. Brak tych uprawnień nie musi spowodować niepowodzenia pierwszego wywołania. AWS dokumentuje, że wywołania mogą działać przez maksymalnie 15 minut podczas konfigurowania subskrypcji. Po nieudanym utworzeniu subskrypcji kolejne wywołania zwracają ten sam błąd AccessDeniedException. Jeśli usługa działała przez kilka pierwszych minut, a następnie zaczęła kończyć się błędem, przyczyny należy szukać tutaj, a nie w poświadczeniach. Po nadaniu uprawnień AWS potrzebuje maksymalnie 2 minut na ukończenie konfiguracji subskrypcji. Wywołanie modelu niedostępnego w danym regionie zakończy się niepowodzeniem niezależnie od poprawności poświadczeń.
FAQ
Czy potrzebuję klucza API Anthropic, aby używać Claude w Bedrock lub Vertex?
Nie. W Amazon Bedrock SDK podpisuje żądania poświadczeniami AWS za pomocą SigV4 albo wysyła klucz API Bedrock, a w Google Cloud wysyła token dostępu Google uzyskany przez Application Default Credentials. W żadnej z tych konfiguracji nie występuje sekret wydany przez Anthropic, a użycie jest rozliczane na koncie chmurowym, a nie przez Anthropic. Dlatego pozostawienie klucza Anthropic w ANTHROPIC_API_KEY stanowi zagrożenie na tych hostach: ogólny klient wskazany na endpoint chmurowy bez problemu wyśle tam ten klucz.
Czy Claude jest dostępny na platformie Azure?
Tak, za pośrednictwem Microsoft Foundry, wcześniej Azure AI Foundry. Należy utworzyć zasób Foundry, wdrożyć w nim model Claude i wywoływać https://{resource}.services.ai.azure.com/anthropic/v1/messages za pomocą klucza wydanego przez Azure w nagłówku api-key albo tokenu bearer Microsoft Entra. Użycie jest rozliczane za pośrednictwem Azure Marketplace w Claude Consumption Units. Pole model w treści żądania musi zawierać nazwę wdrożenia. Nazwa ta jest zgodna z identyfikatorem modelu tylko wtedy, gdy podczas tworzenia wdrożenia zachowano nazwę domyślną. Po utworzeniu wdrożenia nie można jej zmienić.
Gdzie należy przechowywać klucz API Claude na serwerze Linux?
W pliku należącym do root i mającym tryb 600, ładowanym przez EnvironmentFile= w jednostce systemd. systemd odczytuje ten plik jako root, zanim przełączy się na User= jednostki, dlatego konto usługi nie musi mieć do niego dostępu. Klucza nie należy przechowywać w repozytorium, w samym pliku jednostki (który jest dostępny do odczytu dla wszystkich i jest wyświetlany przez systemctl cat) ani w konfiguracji obrazu kontenera, jego warstwach lub metadanych kompilacji.
Dlaczego żądanie API Claude zaczęło zwracać 401, mimo że nic nie zostało zmienione?
Klucz, który osiągnął ustawiony podczas tworzenia termin wygaśnięcia, zwraca 401. Termin wygaśnięcia jest ustalany podczas tworzenia i nie można go później zmienić. Klucze krótkotrwałe wygasają bez ostrzeżenia wysyłanego pocztą elektroniczną. Wygasłego klucza nie można reaktywować. Należy utworzyć klucz zastępczy, zapisać go w pliku środowiskowym, zrestartować usługę, a następnie unieważnić stary klucz. Jeśli klucz jest na pewno aktualny, należy sprawdzić, czy nie przesłania go nieaktualne poświadczenie: ANTHROPIC_API_KEY ustawione na pusty ciąg nadal ma pierwszeństwo przed źródłami federacji i profilu znajdującymi się niżej.