Autenticare Claude API: chiave, Bedrock, Vertex, Foundry

Le quattro modalità di autenticazione dell’API Claude

L’autenticazione dell’API Claude dipende da una sola scelta: quale credenziale il client invia sulla rete. Le possibilità sono quattro e non rappresentano varianti dello stesso meccanismo. L’API Anthropic diretta invia una chiave statica in un’intestazione x-api-key. Amazon Bedrock firma ogni richiesta con credenziali AWS e, in questa configurazione, non viene utilizzata alcuna chiave Anthropic. Google Cloud invia un token di accesso Google a validità breve. Microsoft Foundry utilizza una chiave rilasciata da Azure oppure un token Microsoft Entra.

Questa guida spiega come integrare un SDK (kit di sviluppo software) in un servizio in esecuzione su un server Linux. Se invece stai configurando lo strumento a riga di comando Claude Code, le variabili e il flusso sono diversi: consulta indirizzare Claude Code a 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 rispetto alla documentazione della piattaforma Anthropic nell’agosto 2026. Gli identificatori dei modelli, i prezzi, le versioni degli SDK e la struttura degli endpoint cambiano nel tempo. Per questo la guida rimanda alle pagine dei provider invece di riportare valori destinati a diventare 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 include 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 tratto dalla panoramica dei modelli di Anthropic. Una risposta valida è 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.

La creazione del client è la più semplice delle quattro, perché non c'è nulla da configurare. 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)

È consigliabile mantenere l'identificatore del modello nell'ambiente, accanto alla chiave. I nomi dei modelli cambiano secondo una pianificazione che non dipende da te, quindi ridistribuire il codice per modificare una sola stringa è lavoro evitabile.

Le chiavi vengono create nella Console, dove al momento della creazione scegli la scadenza: i valori predefiniti di 3 ore, 1 giorno, 7 giorni o 30 giorni, una durata personalizzata oppure Never. La scadenza viene 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; la soluzione consiste quindi sempre nel creare una nuova chiave.

Per l'API diretta non è necessario scegliere una regione e l'addebito viene effettuato direttamente sull'organizzazione Anthropic. Gli workspace limitano una chiave a un progetto, che è il modo più semplice per verificare quanto spende un singolo servizio. Per i calcoli alla base di questo addebito, consulta il confronto tra i prezzi API per token e un abbonamento.

C'è un'altra opzione da considerare, perché elimina completamente il secret statico. Workload Identity Federation consente a un workload di scambiare un token OpenID Connect (OIDC) proveniente da un identity provider già considerato attendibile con un token Anthropic a breve durata presso POST /v1/oauth/token; l'SDK rinnova il token prima della scadenza. Non viene mai creato né copiato alcun valore stringa sk-ant-api.... Questa soluzione è adatta a Kubernetes, GitHub Actions e alle VM cloud, che dispongono già di un'identità della piattaforma. Un VPS semplice di solito non dispone di un issuer di questo tipo; su quel sistema, una chiave API in un file è quindi la soluzione corretta, ed è così che viene trattata nel resto della guida.

Percorso 2: credenziali AWS su Amazon Bedrock

Su Bedrock non utilizzi alcuna chiave Anthropic. L'SDK firma ogni richiesta HTTP con AWS Signature Version 4 (SigV4) usando normali credenziali AWS, quindi AWS decide se quell'identità 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. Se non riesce, anche la chiamata a Claude non riuscirà, perché l'SDK segue la stessa catena: prima gli argomenti del costruttore, quindi AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN e AWS_REGION variabili d'ambiente, poi il file di configurazione AWS e il resto della catena standard (SSO, ruoli assunti, ruolo del task ECS, Instance Metadata Service).

Nella costruzione del client cambiano la classe e un argomento.

from anthropic import AnthropicBedrock

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

Qui la regione non è un semplice dettaglio. Gli endpoint Bedrock sono specifici per regione, l'accesso ai modelli viene concesso per regione nella console AWS e la regione fa parte della firma SigV4. Di conseguenza, una firma calcolata per una regione viene rifiutata da un'altra. Imposta AWS_REGION in modo esplicito nell'ambiente del servizio. Anthropic documenta che il client AnthropicBedrock legge AWS_REGION e usa us-east-1 come fallback quando non è impostata, e che non legge ~/.aws/config per la regione. Per questo AWS CLI può elencare correttamente i modelli Claude sullo stesso sistema in cui il processo Python non riesce: AWS CLI legge il file di configurazione, mentre il client non lo fa.

Su un'istanza EC2 associ un ruolo IAM (identity and access management) e nessun secret viene mai scritto su disco, perché Instance Metadata Service fornisce credenziali temporanee all'SDK. Un VPS esterno ad AWS non dispone né di un ruolo dell'istanza né di un metadata service. Devi quindi scegliere tra una coppia di chiavi di accesso a lunga durata di un utente IAM conservata sul sistema, 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 un bearer token tramite AWS_BEARER_TOKEN_BEDROCK, documentato con una durata massima di 12 ore e descritto da AWS come l'opzione meno preferibile.

Il costo viene addebitato al tuo account AWS anziché ad Anthropic, che di solito è il motivo principale per scegliere questa soluzione. Gli endpoint regionali applicano un sovrapprezzo del 10% rispetto all'endpoint globale, come documentato ad agosto 2026. C'è un errore Bedrock che conviene riconoscere perché sembra un problema di autorizzazioni, 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

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 l'account di servizio collegato tramite il metadata server.

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

Su una workstation, il comando di accesso scrive $HOME/.config/gcloud/application_default_credentials.json e l'operazione è conclusa. Su un server è lo strumento sbagliato, perché la credenziale salvata appartiene a una persona e cessa di funzionare quando viene eliminato l'account di quella persona. Fuori da Google Cloud non esiste neppure un metadata server, quindi ADC ricorre a GOOGLE_APPLICATION_CREDENTIALS, che punta a un file di chiavi dell'account di servizio. Questo file JSON è un secret di lunga durata e richiede esattamente la gestione descritta più avanti in questa guida. All'interno di Google Cloud, collega un account di servizio alla VM: non ci sarà alcun file da proteggere.

from anthropic import AnthropicVertex

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

Se si passa dall'SDK alle richieste HTTP dirette, cambiano due aspetti. L'identificatore del modello esce dal corpo della richiesta e passa nel percorso dell'URL, mentre anthropic_version esce dall'header e passa nel corpo, dove deve essere indicato come vertex-2023-10-16. La credenziale è un normale token di accesso Google.

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 regione è un argomento di primo livello. global esegue il routing dinamico per garantire la disponibilità, us e eu sono identificatori multiregione, mentre un nome come us-east5 vincola la richiesta a una singola regione. Come documentato ad agosto 2026, gli endpoint multiregione e regionali costano il 10% in più rispetto a quelli globali. La fatturazione passa dal progetto Google Cloud, quindi quote e fatture sono gestite da Google.

Percorso 4: Microsoft Foundry è il percorso Azure

Se hai cercato Claude su Azure, questa è la sezione che ti interessa: esiste 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 in Azure all'indirizzo https://{resource}.services.ai.azure.com/anthropic/v1/*.

Sono supportati due tipi di credenziali. Il primo è una chiave rilasciata da Azure, disponibile nella scheda Details della distribuzione nel portale Foundry, da inviare in un'intestazione api-key o x-api-key. Il secondo è un token Microsoft Entra. Su un server è in genere la scelta migliore, perché il controllo degli accessi basato sui ruoli di Azure stabilisce 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 identificatore del modello. Per impostazione predefinita i due valori coincidono, ma smettono di coincidere non appena assegni personalmente un nome alla distribuzione. Questa è la causa più comune di un 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. Il supporto per Foundry non è disponibile in tutti gli SDK: secondo la documentazione di agosto 2026, è disponibile per C#, Java, PHP, Python e TypeScript, mentre gli SDK Go e Ruby richiedono il client generico indirizzato all'URL di base di Foundry.

Questa soluzione alternativa presenta un rischio specifico. Se ANTHROPIC_API_KEY è ancora impostata nell'ambiente, il client generico la rileva e invia la chiave Anthropic a un endpoint Microsoft. Rimuovi la variabile dall'ambiente oppure disabilita i valori predefiniti dell'ambiente nel client. I token Entra scadono dopo circa un'ora, quindi un processo di lunga durata deve rinnovarli e non acquisirne uno soltanto all'avvio.

Quanto dura la credenziale sul server?

[
  {
    "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
  }
]

Questi sono i limiti massimi e i valori predefiniti pubblicati da ciascun provider e rilevati ad agosto 2026, non valori misurati. Sono importanti per un solo motivo: indicano per quanto tempo una credenziale divulgata continua a funzionare mentre stai ancora verificando che sia stata divulgata. I token a breve durata in fondo al grafico restano validi per 1 ora ciascuno e l'SDK li rinnova, quindi la breve durata non comporta costi operativi. Un ruolo assunto resta valido per 12 ore. Una chiave creata con il preset di 30 giorni resta valida per 720 ore: è la credenziale che rimane in un file sul server per un mese.

Dove si trova la credenziale su un VPS

Inserisci il secret in un file leggibile soltanto da root e lascia che sia systemd a passarlo al processo. Questa parte non dipende dalla 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 KEY=value in chiaro. Non usare export, virgolette o sintassi della shell, perché è systemd a eseguire il parsing del file, senza passarlo 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 eseguire il downgrade a User=claudeapp. L'account del servizio non deve quindi avere accesso in lettura al file. È sufficiente impostare il file con permessi 600 e proprietario root; per questo il comando install riportato sopra lo configura in questo modo. Avvia il servizio con sudo systemctl enable --now claude-app, quindi verifica con systemctl status claude-app che l'unità abbia raggiunto active (running) invece di riavviarsi in un ciclo continuo.

Evita questi quattro comportamenti, ciascuno per un motivo che puoi verificare direttamente:

• Non scrivere la chiave con Environment= nel file dell'unità. Un'unità in /etc/systemd/system è leggibile da tutti gli utenti, 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 fa nulla per un file già sottoposto a commit, perché la cronologia di git conserva tutto ciò che è stato inserito.
• Non incorporare il secret in un'immagine container. Le righe ENV e i valori --build-arg vengono registrati nei layer dell'immagine, e docker history --no-trunc li restituisce. Eliminare il file in un layer successivo non lo rimuove dal layer precedente. Passa i secret in fase di esecuzione con --env-file oppure usa un file montato.
• Non considerare privato l'ambiente del processo nei confronti di root. sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ restituisce la chiave. L'obiettivo è tenere il secret lontano da tutti gli altri account del server, non da root, che può leggerlo indipendentemente dalle misure adottate.

Quest'ultimo punto definisce il limite di ciò che questa soluzione garantisce. Una variabile d'ambiente è un contenitore adeguato per un secret quando gli unici soggetti che possono leggerla sono il servizio e root. È invece il contenitore sbagliato quando il processo esegue codice che non hai scritto, perché qualsiasi codice eseguito dal processo può leggere il proprio ambiente. Tenere i secret fuori dalla portata di un agente AI tratta questo caso, che è un problema diverso e richiede una soluzione diversa.

Come ruoto la chiave senza downtime?

Ruotala in avanti e revoca quella precedente per ultima.

1. Crea la nuova chiave nella Console, nello stesso workspace di quella 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 mantiene il valore ricevuto al momento dell'avvio. systemctl daemon-reload rilegge i file dell'unità, ma non modifica l'ambiente di un processo in esecuzione; solo un riavvio acquisisce la nuova chiave. Se revochi la chiave al passaggio 1 invece che al passaggio 4, provochi un'interruzione che dura fino al passaggio 3.

Le altre tre modalità ruotano le chiavi 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 si ruota nello stesso modo. Una chiave Foundry viene rigenerata nel portale e quella precedente viene invalidata immediatamente, quindi scrivi il nuovo valore prima di fare clic. I token Entra e i token Anthropic federati non richiedono alcuna rotazione. Questo è il motivo principale per usarli quando possibile.

Mentre sei nella Console, imposta un limite di spesa per il workspace. Una chiave esposta genera costi prima di causare qualsiasi altro problema, e 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 o scaduta. La scadenza è il caso più facile da trascurare, perché il codice non è cambiato e la richiesta funzionava il giorno precedente. 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.

L'SDK ignora la configurazione della federazione e usa invece una chiave. ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN hanno precedenza sulla federazione nell'ordine di precedenza delle credenziali, quindi ciascuno dei due può renderla ininfluente. Il caso più insidioso è questo: una variabile esportata come stringa vuota occupa comunque il relativo slot, quindi ANTHROPIC_API_KEY="" fa sì che l'SDK esegua l'autenticazione con una chiave vuota invece di passare al metodo successivo. Usa unset ANTHROPIC_API_KEY.

401 con il messaggio invariato Authentication failed sulla federazione. Il messaggio è volutamente identico per tutte le possibili cause, così chi effettua la chiamata non può dedurre la configurazione delle regole leggendo il testo dell'errore. Il motivo effettivo è registrato nella pagina della cronologia delle autenticazioni nella Console. Inizia da lì invece di ipotizzare il problema del 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. Esegui prima aws sts get-caller-identity come utente del servizio. Il comando verifica se il server dispone di credenziali AWS utilizzabili e consente di distinguere un problema di credenziali da un problema di accesso al modello o da una regione non corrispondente. L'accesso ai modelli viene concesso per regione nella console AWS ed è facile abilitarlo in una regione mentre si effettuano le chiamate verso un'altra.

FAQ

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

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

Claude è disponibile su Azure?

Sì, tramite Microsoft Foundry, precedentemente Azure AI Foundry. È necessario creare una risorsa Foundry, eseguire il deploy di un modello Claude al suo interno e chiamare https://{resource}.services.ai.azure.com/anthropic/v1/messages usando una chiave emessa da Azure in un header api-key oppure un bearer token Microsoft Entra. L'utilizzo viene addebitato tramite Azure Marketplace in Claude Consumption Units. Il campo model nel corpo della richiesta deve contenere il nome del deployment, che coincide con l'identificatore del modello soltanto finché non si rinomina un deployment.

Dove devo archiviare 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 poterlo leggere. La chiave deve restare fuori dal repository, dal file dell'unità stesso, che è leggibile da tutti e viene stampato da systemctl cat, e dai layer delle immagini dei container, perché docker history --no-trunc ristampa qualsiasi valore impostato con ENV o --build-arg.

Perché le mie richieste API Claude hanno iniziato a restituire 401 senza che cambiassi nulla?

La causa più comune è una chiave arrivata alla scadenza impostata al momento della creazione. La scadenza viene definita durante la creazione, non può essere modificata in seguito e le chiavi a breve durata scadono senza inviare un'email di avviso. Una chiave scaduta non può essere riattivata: è necessario crearne una sostitutiva, scriverla nel file dell'ambiente, riavviare il servizio e revocare la vecchia chiave successivamente. Se la chiave è sicuramente valida, verificare che una credenziale obsoleta non la stia sovrascrivendo: ANTHROPIC_API_KEY impostata su una stringa vuota ha comunque la precedenza su qualsiasi altra origine delle credenziali.