SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Autenticare Claude API: chiave, Bedrock, Vertex e Foundry

Scopri come autenticare un client Claude API su VPS con chiave Anthropic, AWS IAM, Google ADC o Microsoft Entra e proteggere le credenziali sul server.

I percorsi di autenticazione dell'API Claude

L'autenticazione dell'API Claude dipende da una sola decisione: quale credenziale il client invia sulla rete. Anthropic elenca l'API Claude diretta e cinque piattaforme cloud: Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Google managed), Claude Models on Google Cloud (Anthropic managed) e Microsoft Foundry. L'API Anthropic diretta accetta una chiave API o un token a breve durata nell'header Authorization: Bearer e continua ad accettare le chiavi API nell'header legacy x-api-key. Amazon Bedrock supporta la firma delle richieste AWS e le chiavi API Bedrock; in questa configurazione non viene utilizzata alcuna chiave Anthropic. Google Cloud invia un token di accesso Google a breve durata. Microsoft Foundry accetta una chiave rilasciata da Azure o un token Microsoft Entra. Le quattro sezioni seguenti descrivono queste configurazioni delle credenziali. Le offerte gestite da Anthropic su AWS e Google Cloud sono spiegate insieme alle rispettive offerte cloud.

Questa guida descrive come integrare un SDK (kit di sviluppo software) in un servizio in esecuzione su un server Linux. Se invece stai configurando lo strumento da riga di comando Claude Code, le variabili e il flusso sono diversi: consulta configurare Claude Code per usare Bedrock o Vertex. Se il servizio non esiste ancora, crealo prima seguendo creare la prima applicazione Claude API su un VPS, quindi torna qui per configurare la credenziale.

Tutto il contenuto seguente è stato verificato sulla documentazione della piattaforma Anthropic nell'agosto 2026 e nuovamente sulla documentazione di ciascun provider il 16 ottobre 2026. I dettagli sull'accesso ai modelli Bedrock sono stati verificati nuovamente sulla documentazione AWS il 19 ottobre 2026. Le pagine Anthropic relative a tutti e quattro i percorsi, alle chiavi API e alle versioni API sono state verificate nuovamente il 27 ottobre 2026. Le pagine Anthropic relative a Microsoft Foundry, a entrambi gli endpoint Bedrock, al percorso gestito da Google, a Claude Platform on AWS, all'autenticazione, a Workload Identity Federation e alle versioni API sono state verificate nuovamente il 10 novembre 2026, insieme al changelog dell'SDK Ruby. Gli identificativi dei modelli, i prezzi, le versioni degli SDK e la struttura degli endpoint cambiano nel tempo. Per questo questa guida collega le pagine dei provider invece di riportare valori che diventerebbero obsoleti.

Percorso 1: una chiave API Anthropic

Questo è il percorso diretto, ed è l'unico in cui Anthropic emette il secret. Le richieste vengono inviate all'endpoint Messages sull'host API di Anthropic e ogni richiesta contiene tre 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"}]}'

Sostituisci MODEL_ID con un identificatore attuale disponibile nella panoramica dei modelli di Anthropic. Una risposta corretta è un JSON che contiene un array content e un oggetto usage. Una chiave errata o scaduta restituisce HTTP 401 con authentication_error. L'assenza dell'header anthropic-version causa un errore distinto, perché questo header è obbligatorio per ogni richiesta; gli SDK lo impostano automaticamente. A ottobre 2026, la documentazione di Anthropic presenta Authorization: Bearer come metodo principale per inviare la chiave e definisce x-api-key legacy, ma entrambi sono accettati, quindi il comando precedente continua a funzionare. Le versioni principali attuali degli SDK inviano la chiave anche come Authorization: Bearer, quindi un proxy o un gateway che legge X-Api-Key deve essere aggiornato quando esegui l'upgrade. La versione 2023-06-01 nel comando è ancora accettata; la versione API più recente di Anthropic è 2026-10-21, che queste versioni degli SDK inviano per impostazione predefinita e che rifiuta alcuni parametri di richiesta meno recenti, come temperature.

La creazione del client è l'operazione più breve tra queste configurazioni, perché non c'è nulla da costruire. Ogni SDK ufficiale legge autonomamente ANTHROPIC_API_KEY dall'ambiente.

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)

Conviene mantenere l'identificatore del modello nell'ambiente insieme alla chiave. I nomi dei modelli cambiano secondo una pianificazione che non controlli e ridistribuire il codice per modificare una singola stringa è un lavoro evitabile.

Le chiavi vengono create nella Console, dove al momento della creazione scegli una scadenza: i valori predefiniti di 3 ore, 1 giorno, 7 giorni o 30 giorni, una durata personalizzata oppure Never, in base al periodo massimo di scadenza previsto dalla tua organizzazione. La scadenza è fissata al momento della creazione e non può essere modificata in seguito. Anthropic invia un'email al creatore della chiave prima della scadenza di una chiave con durata lunga, ma una chiave con durata breve scade senza alcuna email di avviso. Una chiave scaduta restituisce 401 e non può essere riattivata, quindi la soluzione consiste sempre nel creare una nuova chiave.

Per l'API diretta non devi scegliere alcuna regione e l'addebito viene applicato direttamente alla tua organizzazione Anthropic. Gli workspace limitano una chiave a un solo progetto; questo è il modo più semplice per vedere quanto spende un singolo servizio. Quando crei la chiave di un server, limitane l'ambito al relativo workspace: una chiave di un account personale o di servizio non limitata a un workspace deve inviare un header anthropic-workspace-id a ogni richiesta, altrimenti l'API risponde 400 con invalid_request_error. Per un servizio, scegli una chiave di un account di servizio, perché una chiave personale smette di funzionare quando la persona che l'ha creata lascia l'organizzazione. Per i calcoli alla base di questo addebito, consulta il confronto tra i prezzi API per token e un abbonamento.

Qui rientra anche un'altra opzione, perché elimina completamente il secret statico. Workload Identity Federation consente a un workload di scambiare un token OpenID Connect (OIDC) emesso da un identity provider già considerato attendibile con un token Anthropic a durata breve presso POST /v1/oauth/token; lo SDK aggiorna il token prima della scadenza. Non viene mai generata né copiata alcuna stringa sk-ant-api.... Questa soluzione è adatta a Kubernetes, GitHub Actions e alle VM cloud, che dispongono già di un'identità della piattaforma. In genere un VPS semplice non dispone di un issuer di questo tipo, quindi su quel server una chiave API in un file è la soluzione corretta; il resto di questa guida la considera come riferimento.

Percorso 2: credenziali AWS su Amazon Bedrock

Su Bedrock non usi alcuna chiave Anthropic. Con le credenziali AWS, l'SDK firma ogni richiesta HTTP con AWS Signature Version 4 (SigV4) e AWS decide se l'identità chiamante può invocare il modello.

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

aws sts get-caller-identity stampa il numero dell'account e l'ARN (Amazon Resource Name) dell'identità risolta dalle credenziali. Eseguilo prima di qualsiasi altra operazione quando usi SigV4. Per SigV4, l'SDK risolve le credenziali del costruttore, le credenziali dell'ambiente e la catena standard delle credenziali AWS; la selezione della regione è separata. Nel client Python AnthropicBedrock, una chiave API Bedrock fornita tramite api_key o AWS_BEARER_TOKEN_BEDROCK genera ValueError se passi anche aws_access_key, aws_secret_key, aws_session_token o aws_profile. Senza questi argomenti espliciti, la chiave seleziona l'autenticazione bearer invece della catena delle credenziali AWS. Il client TypeScript assegna precedenza alla chiave API Bedrock rispetto alle credenziali AWS esplicite. Il comando STS non verifica l'autenticazione bearer.

Nella costruzione del client cambiano la classe e un argomento.

from anthropic import AnthropicBedrock

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

AnthropicBedrock gestisce l'integrazione InvokeModel di Bedrock. A ottobre 2026, Anthropic documenta anche Claude in Amazon Bedrock, con un endpoint Messages API all'indirizzo https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages per Claude Opus 4.7 e i modelli successivi, raggiungibile tramite un client AnthropicBedrockMantle dello stesso pacchetto. Supporta le credenziali AWS e i bearer token Bedrock; i requisiti per accedere ai modelli differiscono tra i due endpoint, come spiegato di seguito.

Presta attenzione all'aggiornamento nella riga pip install -U. Al 27 ottobre 2026, l'SDK più recente invia per impostazione predefinita la versione API 2026-10-21, anche tramite Bedrock, e Anthropic documenta che gli ID modello con versione nell'ARN elencati per Claude Opus 4.6 e versioni precedenti non supportano quella versione su Bedrock e possono restituire un errore 400. Se un servizio utilizza uno di questi modelli, mantieni l'SDK sulla versione attualmente in uso e fissala esplicitamente, oppure sposta prima il servizio su un modello Claude 4.7 o successivo.

Qui la regione è un parametro operativo. Gli endpoint Bedrock sono specifici per regione, i modelli Claude disponibili cambiano da una regione all'altra e la regione fa parte della firma SigV4; per questo una firma calcolata per una regione viene rifiutata da un'altra. Imposta esplicitamente AWS_REGION nell'ambiente del servizio, perché gli SDK non si comportano allo stesso modo quando il parametro viene omesso. Come documentato a ottobre 2026, il client Python AnthropicBedrock legge AWS_REGION o AWS_DEFAULT_REGION, poi la regione della sessione boto3 o del profilo AWS, incluso ~/.aws/config, e genera ValueError se non riesce a risolvere alcun valore. Il client TypeScript legge AWS_REGION, usa us-east-1 come fallback quando non è impostato e non legge ~/.aws/config per determinare la regione. Per questo la AWS CLI può elencare correttamente i modelli Claude sulla stessa macchina in cui un processo Node chiama la regione errata: la CLI ha letto il file di configurazione, mentre il client non lo ha fatto.

Su un'istanza EC2 associ un ruolo IAM (identity and access management) e nessun secret viene scritto su disco, perché il servizio di metadati dell'istanza fornisce all'SDK credenziali temporanee. Un VPS esterno ad AWS non dispone né di un ruolo dell'istanza né di un servizio di metadati. Devi quindi scegliere tra una coppia di chiavi di accesso a lunga durata di un utente IAM memorizzata sul server, che appartiene alla stessa categoria di secret di una chiave Anthropic, e la federazione: esegui l'autenticazione tramite il tuo identity provider, chiama AWS STS (security token service) e usa le credenziali temporanee restituite. Bedrock accetta anche le chiavi API Bedrock, ovvero bearer token passati tramite AWS_BEARER_TOKEN_BEDROCK, e AWS ne documenta due tipi. Una chiave a breve durata è valida fino a 12 ore, oppure per la durata della sessione che l'ha generata se inferiore, eredita i permessi dell'identità IAM che l'ha generata ed è il tipo raccomandato da AWS per la produzione. Una chiave a lunga durata resta valida fino alla scadenza scelta al momento della creazione, ad esempio 30 o 90 giorni con --credential-age-days, oppure non scade se quel parametro API viene omesso; la Console crea un utente IAM associato e AWS ne raccomanda l'uso soltanto per la fase di esplorazione. Una chiave a lunga durata funziona solo nella regione in cui è stata generata; se la usi in un'altra regione restituisce Credential should be scoped to a valid region.

L'addebito viene applicato al tuo account AWS anziché ad Anthropic, che di solito è il motivo principale per scegliere questa soluzione. Come documentato a ottobre 2026, gli endpoint regionali applicano un sovrapprezzo del 10% rispetto all'endpoint globale. Claude Platform su AWS è un prodotto separato: è gestito da Anthropic, viene fatturato da AWS tramite AWS Marketplace e si autentica con SigV4 o con una chiave API generata nella AWS Console; le chiavi della Claude Console non funzionano. Usa un client AnthropicAWS, che Anthropic contrassegna come beta. Esiste un errore Bedrock che conviene riconoscere perché sembra un problema di permessi, ma non lo è: 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. Si tratta del routing del modello e nessuna modifica alle credenziali lo risolverà.

Percorso 3: credenziali Google su Vertex AI

La documentazione di Anthropic ora chiama questo percorso Claude Models on Google Cloud (Google managed), che Google gestisce come parte di Agent Platform, il nuovo nome di Google per l'offerta derivata da Vertex AI. L'host aiplatform.googleapis.com, l'extra anthropic[vertex] e la classe AnthropicVertex mostrati di seguito non cambiano.

Google Cloud usa le Application Default Credentials (ADC), un ordine di ricerca fisso seguito dalle librerie di autenticazione Google per trovare una credenziale senza doverla specificare. ADC controlla prima GOOGLE_APPLICATION_CREDENTIALS, poi il file scritto da gcloud auth application-default login e infine il service account associato tramite il metadata server.

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

Su una workstation, il login scrive $HOME/.config/gcloud/application_default_credentials.json e la procedura è terminata. Su un server, evita di memorizzare le credenziali di un utente umano; il comando supporta anche la service account impersonation. Al di fuori di Google Cloud non è disponibile neppure il metadata server Google, quindi usa GOOGLE_APPLICATION_CREDENTIALS per indicare ad ADC un file di configurazione Workload Identity Federation oppure un file di chiavi di un service account. Un file JSON con la chiave di un service account è un secret di lunga durata e deve essere gestito esattamente come descritto più avanti in questa guida. All'interno di Google Cloud, associa un service account alla VM: in questo modo non c'è alcun file da proteggere. Qualunque identità venga trovata da ADC deve disporre di un ruolo IAM che includa il permesso aiplatform.endpoints.predict, ad esempio Agent Platform User (roles/aiplatform.user).

from anthropic import AnthropicVertex

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

Se passi dall'SDK alle richieste HTTP dirette, cambiano due aspetti. L'identificatore del modello esce dal body della richiesta e viene inserito nel percorso dell'URL, mentre anthropic_version esce dall'header e viene inserito nel body. Al 27 ottobre 2026, la documentazione di Anthropic accetta in quel punto vertex-2023-10-16 oppure la versione API più recente 2026-10-21. La credenziale è un normale token di accesso Google. Nel comando seguente, gcloud auth print-access-token usa il login del gcloud CLI invece di ADC; esegui quindi prima gcloud auth login o gcloud init sulla macchina in cui effettui il 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"}]}'

La region è un argomento fondamentale. global esegue il routing dinamico per garantire la disponibilità, us e eu sono identificatori multi-region, mentre un nome come us-east5 vincola il servizio a una singola region. A ottobre 2026, Anthropic documenta endpoint a singola region solo per Claude Sonnet 4.6 e versioni precedenti; i modelli più recenti usano gli endpoint globali o multi-region. Gli endpoint multi-region e regionali costano il 10% in più rispetto a quelli globali, come documentato a ottobre 2026. La fatturazione passa dal progetto Google Cloud, quindi quote e fatture sono gestite da Google.

Al 27 ottobre 2026, Anthropic documenta anche una seconda offerta Google Cloud, con una struttura della richiesta diversa. In Claude Models on Google Cloud (Anthropic managed), Anthropic gestisce direttamente la Claude API all'indirizzo claude.googleapis.com, raggiunto tramite un client AnthropicGoogleCloud. L'autenticazione usa comunque le credenziali Google Cloud, incluse le ADC, ma la richiesta è simile a quella dell'API diretta: model rimane nel body e la versione viene indicata nell'header anthropic-version. L'accesso usa ruoli IAM propri (roles/claude.user e ruoli correlati), la configurazione crea una nuova organizzazione Anthropic per il progetto e l'utilizzo viene fatturato tramite Google Cloud Marketplace. Se gli URL delle richieste contengono aiplatform e terminano con :rawPredict, stai usando il percorso gestito da Google descritto in questa sezione.

Percorso 4: Microsoft Foundry è il percorso Azure

Se hai cercato Claude su Azure, questa è la sezione che ti serve. È disponibile un percorso supportato. Claude viene eseguito in Microsoft Foundry (in precedenza Azure AI Foundry) e viene fatturato tramite Azure Marketplace in Claude Consumption Units. Devi creare una risorsa Foundry, distribuire al suo interno un modello Claude e chiamare un endpoint ospitato da Azure all'indirizzo https://{resource}.services.ai.azure.com/anthropic/v1/*.

Sono disponibili due credenziali. La prima è una chiave rilasciata da Azure nella scheda Details della distribuzione, nel portale Foundry, e inviata in un header api-key o x-api-key. La seconda è un token Microsoft Entra. Su un server è la scelta preferibile, perché il controllo degli accessi basato sui ruoli di Azure determina chi può chiamare l'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"}]}'

Il campo model contiene il nome della distribuzione, non un identificativo del modello. Per impostazione predefinita i due valori coincidono, ma smettono di coincidere non appena assegni un nome personalizzato alla distribuzione. Questa è la causa più comune dell'errore Deployment not found in una richiesta altrimenti corretta. Gli SDK Python e TypeScript leggono ANTHROPIC_FOUNDRY_API_KEY e ANTHROPIC_FOUNDRY_RESOURCE dall'ambiente. Come documentato il 10 novembre 2026, Foundry supporta tutti i sette SDK ufficiali: C#, Go, Java, PHP, Python, Ruby e TypeScript. Go utilizza il pacchetto dedicato foundry (go get github.com/anthropics/anthropic-sdk-go/v2/foundry). Ruby ha ricevuto un Anthropic::FoundryClient dedicato nella versione 2.5.0 della gem, rilasciata il 4 novembre 2026. Prima di tale versione, il codice Ruby doveva configurare il client generico con l'URL di base Foundry.

Configurare un client generico con l'URL di base Foundry presenta ancora un rischio, sia nel codice Ruby scritto prima della versione 2.5.0 sia nella CLI ant, che negli esempi Foundry di Anthropic viene configurata nello stesso modo. Se non passi esplicitamente le credenziali al client generico e nell'ambiente è ancora impostata ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN, il client la utilizza e invia la tua credenziale Anthropic a un endpoint Microsoft. Rimuovi la variabile dall'ambiente oppure passa esplicitamente al client la chiave o il token Foundry. In Ruby, il passaggio a Anthropic::FoundryClient, che accetta la chiave Foundry o un provider di token Entra, è la soluzione più pulita. Un token di accesso Entra ha una durata predefinita casuale compresa tra 60 e 90 minuti. Un processo di lunga durata deve quindi rinnovarlo invece di acquisirne uno soltanto all'avvio.

Quanto dura la credenziale presente sul server?

GraficoDocumented credential lifetime by route, hours
I dati alla base di questo grafico
[
  {
    "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
  }
]

Si tratta di limiti massimi e valori predefiniti pubblicati dai singoli provider e rilevati a ottobre 2026, non di valori misurati. Sono importanti per un solo motivo: indicano per quanto tempo una credenziale fuoriuscita continua a funzionare mentre si sta ancora accertando la fuoriuscita. Il token federato Anthropic in fondo al grafico dura per impostazione predefinita fino a 1 ore ed è inoltre limitato al doppio della durata residua del token del provider di identità. Un token di accesso Microsoft Entra non ha un valore predefinito unico: Microsoft assegna a ciascun token una durata casuale compresa tra 60 e 90 minuti, con una media di 75 minuti. Nel grafico è riportato al limite superiore di 1.5 ore. Anche questo valore predefinito varia in base al client, alla risorsa e al fatto che Conditional Access sia abilitato nel tenant. Quando sia il client sia la risorsa supportano Continuous Access Evaluation, Entra può estendere la durata a 24-28 ore e revocare invece il token quasi in tempo reale in caso di eventi come la disabilitazione dell'account. Una policy sulla durata dei token del tenant può impostarla da 10 minuti a 23:59:59. Gli SDK aggiornano automaticamente i token federati Anthropic. Su Foundry, configura un provider di token Entra per aggiornare i token invece di passare una stringa di token fissa. Una regola di federazione può impostare una durata del token compresa tra un minuto e 24 ore. La procedura guidata Connect workload della Console inserisce 10 minuti come valore predefinito, quindi leggi la regola invece di presumere il valore predefinito. Un ruolo assunto e una chiave API a breve termine Bedrock hanno entrambi una durata di 12 ore. Una chiave API a lungo termine Bedrock non compare nel grafico perché non ha un limite massimo fisso: resta valida fino alla scadenza scelta al momento della creazione oppure non scade se CredentialAgeDays è stato omesso dalla chiamata API. Per questo AWS ne raccomanda l'uso soltanto per attività esplorative. Una chiave creata con il valore predefinito di 30 giorni resta valida per 720 ore. È la credenziale che rimane in un file sul server per un mese.

Dove risiede la credenziale su un VPS

Inserire il secret in un file leggibile soltanto da root e lasciare che systemd lo passi al processo. Questa parte non dipende da alcuna versione dell’SDK, quindi conviene configurarla una volta sola e correttamente.

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

Il file contiene righe semplici nel formato KEY=value. Non usare export, virgolette o sintassi della shell, perché systemd esegue il parsing direttamente invece di passare il contenuto a una 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 legge EnvironmentFile= come root, prima di passare a User=claudeapp, quindi l’account del servizio non deve avere accesso in lettura al file. È sufficiente usare la modalità 600 con root come proprietario; per questo il comando install riportato sopra la imposta in questo modo. Avviare il servizio con sudo systemctl enable --now claude-app, quindi verificare con systemctl status claude-app che l’unità abbia raggiunto active (running) invece di riavviarsi in un ciclo continuo.

Evitare questi quattro comportamenti, per motivi che è possibile verificare direttamente:

  • Non scrivere la key usando Environment= all’interno del file dell’unità. Un’unità in /etc/systemd/system è leggibile da tutti, quindi systemctl cat claude-app restituisce il secret a qualsiasi utente locale.
  • Non eseguire il commit del file. .gitignore esclude un nuovo file dal commit, ma non agisce su un file già sottoposto a commit, perché la cronologia di git conserva tutto ciò che le è stato fornito.
  • Non incorporare il secret in un’immagine container. I valori ENV restano nella configurazione dell’immagine e gli argomenti di build sono visibili nella cronologia dell’immagine o nei metadati di provenienza. Eliminare il file in un layer successivo non lo rimuove dal layer precedente. Passare i secret a runtime con --env-file oppure usare un file montato.
  • Non considerare privato l’ambiente del processo rispetto a root. sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n' restituisce la key. Il comando che legge il file richiede direttamente sudo; una redirezione dell’input della shell viene eseguita prima di sudo e usa i permessi dell’account corrente. L’obiettivo è impedire l’accesso al secret a tutti gli altri account del sistema, non a root, che può leggerlo indipendentemente dalle misure adottate.

Quest’ultimo punto definisce i limiti di questa soluzione. Il file accessibile soltanto da root protegge la key memorizzata, ma qualsiasi codice eseguito dall’account del servizio può leggere l’ambiente del processo e i processi figli lo ereditano. Questo non è il contenitore corretto quando il processo esegue codice non scritto da voi, perché tutto ciò che il processo può eseguire può leggere il proprio ambiente. Impedire a un agente AI di accedere ai secret tratta questo caso, che rappresenta un problema diverso e richiede una soluzione diversa.

Come ruotare la chiave senza downtime?

Ruotala in avanti e revoca quella precedente per ultima. Il riavvio del singolo servizio riportato di seguito interrompe brevemente il servizio; per mantenere la disponibilità senza interruzioni è necessaria un'altra istanza che gestisca le richieste durante il riavvio.

  1. Crea la nuova chiave nella Console, nello stesso workspace della chiave precedente.
  2. Scrivila in /etc/claude-app/env con sudoedit.
  3. Esegui sudo systemctl restart claude-app.
  4. Verifica che il servizio risponda alle richieste, quindi revoca la chiave precedente nella Console.

EnvironmentFile viene letto all'avvio dell'unità, quindi un processo in esecuzione conserva il valore ricevuto al momento dell'avvio. systemctl daemon-reload rilegge i file dell'unità e non modifica l'ambiente di un processo in esecuzione; solo un riavvio acquisisce la nuova chiave. Se revochi la chiave nel passaggio 1 invece che nel passaggio 4, provochi un'interruzione che dura fino al passaggio 3.

Le route cloud vengono ruotate presso il provider. Un utente IAM supporta contemporaneamente due chiavi di accesso attive: crea la seconda, distribuiscila, quindi elimina la prima. Una chiave di un account di servizio Google viene ruotata nello stesso modo. Una risorsa Foundry contiene due chiavi; la rigenerazione di una rende immediatamente inutilizzabile il valore precedente. Perciò sposta il servizio sull'altra chiave prima di rigenerare quella attualmente in uso. I token Entra e i token Anthropic federati non richiedono la rotazione manuale dei token. Questo è l'argomento più forte per usarli quando possibile.

Mentre sei nella Console, imposta un limite di spesa per il workspace. Una chiave divulgata comporta innanzitutto costi elevati; limitare quanto può spendere un agent su un VPS illustra i controlli disponibili.

Perché il client restituisce 401 o 403?

401 con authentication_error sull'API diretta. La chiave è errata, revocata oppure scaduta. La scadenza è l'aspetto che viene trascurato più spesso, perché il codice non è cambiato e la richiesta funzionava il giorno prima. Controlla la colonna della scadenza della chiave nella Console oppure leggi expires_at dall'Admin API, dove il valore è null per le chiavi senza scadenza. Una chiave personale smette inoltre di funzionare quando il relativo proprietario lascia l'organizzazione.

L'SDK ignora la configurazione della federazione e usa invece una chiave. ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN hanno una precedenza superiore alla federazione nell'ordine di priorità delle credenziali, quindi ciascuno dei due può avere la precedenza su di essa. Il caso più insidioso è una variabile esportata come stringa vuota: occupa comunque il relativo slot, quindi ANTHROPIC_API_KEY="" induce l'SDK ad autenticarsi con una chiave vuota invece di passare al metodo successivo. Usa unset ANTHROPIC_API_KEY.

401 con il messaggio generico Authentication failed sulla federazione. Il messaggio è intenzionalmente identico per tutte le possibili cause, così il chiamante non può individuare la configurazione delle regole leggendo il testo dell'errore. Il motivo effettivo viene registrato nella pagina della cronologia di autenticazione della Console. Inizia da lì invece di formulare ipotesi sul JWT.

403 su Foundry. Il token è stato autenticato, ma l'account Azure non dispone di un ruolo che autorizzi la chiamata. Assegna un ruolo Azure RBAC, ad esempio Foundry User (in precedenza Azure AI User) o Cognitive Services User, all'identità che esegue la richiesta.

Qualsiasi errore su Bedrock. Per l'autenticazione SigV4, esegui prima aws sts get-caller-identity come utente del servizio. Il comando verifica se il server dispone di credenziali AWS utilizzabili e permette di distinguere un problema di credenziali da un problema di accesso al modello o da una regione non corretta. Dal 29 ottobre 2026, AWS abilita l'accesso a molti modelli al primo utilizzo nelle regioni commerciali, se sono disponibili le autorizzazioni AWS Marketplace richieste; alcuni modelli richiedono tuttavia un accesso separato a livello di account. Per i modelli Anthropic chiamati tramite il percorso InvokeModel è necessario compilare prima un modulo una tantum relativo al caso d'uso per ogni account, oppure una sola volta per un'intera AWS Organization; nelle regioni con adesione esplicita è necessario ripetere la procedura. Finché la richiesta non viene approvata, la chiamata restituisce AccessDeniedException. AWS specifica che il modulo non si applica all'endpoint bedrock-mantle. La prima chiamata a un modello in un account avvia inoltre in background la sottoscrizione AWS Marketplace di Bedrock. La sottoscrizione richiede un'identità con le autorizzazioni aws-marketplace:Subscribe, aws-marketplace:Unsubscribe e aws-marketplace:ViewSubscriptions. L'assenza di queste autorizzazioni non causa necessariamente un errore nella prima chiamata: AWS specifica che le chiamate possono riuscire per un massimo di 15 minuti durante la configurazione della sottoscrizione. Dopo il fallimento della sottoscrizione, le chiamate successive restituiscono lo stesso AccessDeniedException. Se un servizio funziona per i primi minuti e poi inizia a fallire, la causa è probabilmente questa e non un problema delle credenziali. Dopo l'assegnazione delle autorizzazioni, AWS può impiegare fino a 2 minuti per completare la sottoscrizione. Un modello non disponibile nella regione usata per la chiamata fallisce indipendentemente dalla validità delle credenziali.

FAQ

Mi serve una chiave API Anthropic per usare Claude su Bedrock o Vertex?

No. Su Amazon Bedrock, l'SDK firma le richieste con le credenziali AWS usando SigV4 oppure invia una chiave API Bedrock; su Google Cloud invia un token di accesso Google ottenuto tramite Application Default Credentials. In nessuna delle due configurazioni esiste un secret rilasciato da Anthropic e l'utilizzo viene addebitato all'account cloud, non ad Anthropic. Per questo motivo, una chiave Anthropic lasciata in ANTHROPIC_API_KEY rappresenta un rischio su questi host: un client generico configurato per un endpoint cloud la invierà senza problemi anche a quell'endpoint.

Claude è disponibile su Azure?

Sì, tramite Microsoft Foundry, precedentemente denominato Azure AI Foundry. Si crea una risorsa Foundry, si distribuisce un modello Claude al suo interno e si chiama https://{resource}.services.ai.azure.com/anthropic/v1/messages usando una chiave rilasciata da Azure nell'header api-key oppure un token bearer Microsoft Entra. L'utilizzo viene addebitato tramite Azure Marketplace in Claude Consumption Units. Il campo model nel corpo della richiesta deve contenere il nome della distribuzione, che corrisponde all'identificatore del modello solo se è stato mantenuto il nome predefinito durante la creazione della distribuzione; il nome non può essere modificato in seguito.

Dove devo memorizzare la chiave API Claude su un server Linux?

In un file di proprietà di root con modalità 600, caricato tramite EnvironmentFile= in un'unità systemd. systemd legge il file come root prima di passare a User= dell'unità, quindi l'account del servizio non deve potervi accedere. La chiave non deve trovarsi nel repository, nel file dell'unità stesso, che è leggibile da tutti e viene stampato da systemctl cat, né nella configurazione dell'immagine del container, nei layer o nei metadati della build.

Perché la mia richiesta all'API Claude ha iniziato a restituire 401 senza che cambiassi nulla?

Una chiave che raggiunge la scadenza impostata al momento della creazione restituisce 401. La scadenza viene definita durante la creazione e non può essere modificata in seguito; le chiavi con durata breve scadono senza inviare un'e-mail di avviso. Una chiave scaduta non può essere riattivata. Creare quindi una sostituzione, scriverla nel file dell'ambiente, riavviare il servizio e revocare successivamente la vecchia chiave. Se la chiave è sicuramente ancora valida, verificare che una credenziale obsoleta non la stia sovrascrivendo: ANTHROPIC_API_KEY impostata su una stringa vuota mantiene comunque la precedenza rispetto alle origini federation e profile elencate sotto di essa.

Questo articolo ti è stato utile?

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