Autenticazione

La Claude API supporta tre modi per autenticare le richieste:

Le chiavi API e Workload Identity Federation garantiscono lo stesso accesso agli endpoint della Claude API. Scegli le chiavi API per iniziare rapidamente: una chiave personale per il tuo sviluppo, oppure una chiave di service account per qualsiasi cosa condivisa. Passa a Workload Identity Federation quando il tuo workload dispone già di un'identità rilasciata dalla piattaforma che puoi federare. Usa App Attest per le app iOS e macOS che distribuisci agli utenti finali.

Chiavi API

Le "API keys" (chiavi API) sono segreti statici che generi nella Claude Console e invii a ogni richiesta nell'header x-api-key.

Tipi di chiave

Quando crei una chiave, ne scegli il tipo, che determina cosa la chiave può fare, dove funziona e quando smette di funzionare:

Le chiavi personali e le chiavi di service account sono basate su un'identità: ciascuna appartiene a un utente o a un service account che la tua organizzazione già gestisce, e ogni richiesta agisce come quell'identità. Quando quell'identità viene rimossa dall'organizzazione, la chiave smette di funzionare. Ciò significa che le chiavi non sopravvivranno accidentalmente alle persone o ai workload che le possiedono. Preferiscile alle chiavi di workspace per le nuove integrazioni.

Usa una chiave personale per il tuo sviluppo e i tuoi script. Una chiave personale condivisa agisce come una sola persona e smette di funzionare quando questa se ne va. Per workload condivisi o automatizzati (CI, servizi di produzione), chiedi a un amministratore dell'organizzazione di creare un service account in modo che il workload abbia una propria identità.

Le chiavi API di workspace funzionano ancora ma vanno considerate legacy; sono preferibili le chiavi basate su identità o Workload Identity Federation. Per migrare, consulta Sostituzione delle chiavi API di workspace.

Crea e usa una chiave

• Crea una chiave: Vai a Settings → API keys nella Claude Console e fai clic su Create key. Assegna un nome alla chiave e scegli una scadenza. Imposta Linked account su te stesso per una chiave personale, oppure su un service account per una chiave condivisa tra più utenti. Puoi anche limitare la chiave a un workspace specifico, il che ti permette di evitare di impostare manualmente un ID di workspace nelle richieste future.
• Usa la chiave: Imposta l'header x-api-key nelle richieste HTTP dirette, oppure imposta la variabile d'ambiente ANTHROPIC_API_KEY e gli SDK client la rileveranno automaticamente.

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Archivia le chiavi API in un secrets manager, ruotale periodicamente e disabilita o elimina qualsiasi chiave che sospetti sia stata compromessa. Nella pagina API keys, Disable è reversibile (l'Admin API riporta lo status della chiave come "inactive", e Re-enable lo riporta a "active"), mentre Delete è permanente: la chiave viene archiviata e compare ancora in List API Keys con status: "archived". Le chiavi scadute possono solo essere eliminate. Puoi anche impostare una scadenza quando crei una chiave per limitare il tempo in cui una credenziale compromessa rimane utilizzabile.

client = Anthropic(api_key="my-anthropic-api-key")
# oppure, con ANTHROPIC_API_KEY impostata nell'ambiente:
client = Anthropic()

Seleziona un workspace

Le chiavi API create per un workspace specifico funzionano solo in quel workspace, e le richieste API che usano queste chiavi possono omettere l'ID del workspace.

Se la tua chiave API non è limitata a un workspace, devi specificare l'ID del workspace nell'header anthropic-workspace-id per ogni richiesta. Consulta l'esempio seguente per vedere come impostare questo header in una richiesta o negli SDK.

L'Admin API accetta una chiave personale o una chiave di service account solo se la chiave non è limitata a un workspace specifico.

Puoi trovare l'ID di un workspace nella colonna ID di Settings → Workspaces nella Claude Console, oppure chiamando l'endpoint List Workspaces. Nessuno dei due elenca l'ID del Default Workspace: leggilo dall'header di risposta anthropic-workspace-id di qualsiasi richiesta eseguita lì (ad esempio, una effettuata con una chiave di workspace del Default Workspace), oppure da scope.workspace_id di tale chiave in List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Obbligatorio in ogni richiesta per una chiave multi-workspace.
# Ometti extra_headers per una chiave a workspace singolo.
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# Oppure impostalo una volta per ogni richiesta da questo client:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Se una richiesta effettuata con una chiave non limitata a un workspace omette l'header, l'API restituisce un errore 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Un valore dell'header che non è un ID di workspace valido restituisce un errore 400 invalid_request_error con il messaggio anthropic-workspace-id header must be a valid workspace ID. Se il workspace non esiste, oppure l'utente o il service account della chiave non vi ha accesso, l'API restituisce un errore 404 not_found_error con il messaggio Workspace `<id>` not found., la stessa risposta di qualsiasi workspace sconosciuto.

Workload Identity Federation seleziona invece un workspace al momento dello scambio del token; consulta il riferimento WIF per i dettagli.

Scadenza delle chiavi

Quando crei una chiave API dalla pagina API keys nella Claude Console, scegli una scadenza: un valore predefinito (3 ore, 1 giorno, 7 giorni o 30 giorni), una durata personalizzata, oppure Never per le chiavi che archivi in un secrets manager e ruoti autonomamente. Se la tua organizzazione ha una policy di scadenza massima, la Console limita i valori predefiniti e le durate personalizzate al massimo previsto dalla policy, e Never non è disponibile. Le chiavi esistenti mantengono il loro comportamento attuale; la scadenza viene impostata al momento della creazione e non può essere modificata successivamente. La stessa scelta di scadenza si applica quando crei una chiave Admin API nella Claude Console.

Anthropic invia un'email al creatore della chiave all'avvicinarsi della scadenza: 7 giorni prima della scadenza per le chiavi create con una durata di almeno 14 giorni, e 1 giorno prima per le chiavi con una durata di almeno 7 giorni. Le chiavi con durate più brevi scadono senza email di avviso.

Dopo la scadenza di una chiave, le richieste effettuate con essa restituiscono un 401 authentication_error. Crea una nuova chiave per ripristinare l'accesso; le chiavi scadute non possono essere riattivate.

La tabella delle chiavi API nella Console mostra la scadenza di ogni chiave, e l'Admin API riporta il timestamp expires_at di ogni chiave negli endpoint List API Keys e Retrieve API Key, così puoi verificare e ruotare le chiavi prima che scadano. Il campo è null per le chiavi senza scadenza.

La scadenza limita la durata di una credenziale compromessa, ma non sostituisce una corretta gestione dei segreti. Indipendentemente dalla scadenza, archivia le chiavi in un secrets manager e disabilita o elimina qualsiasi chiave che sospetti sia stata compromessa.

Sostituzione delle chiavi API di workspace

Se hai una chiave di workspace, potresti volerla sostituire con Workload Identity Federation oppure con una chiave personale o di service account. Questo offre maggiore sicurezza e osservabilità.

Consulta Workload Identity Federation per i dettagli sulla configurazione di Workload Identity Federation, che è preferibile rispetto alle chiavi a lunga durata.

Per sostituire una chiave di workspace con una chiave personale o di service account:

1. Decidi il tipo di chiave. I tuoi strumenti personali dovrebbero usare una chiave personale. Un workload condiviso o non presidiato dovrebbe usare una chiave di service account.
2. Crea un service account se necessario. Potresti dover chiedere a un amministratore dell'organizzazione di crearne uno in Settings → Service accounts e di aggiungerlo al workspace pertinente.
3. Crea la nuova chiave. Creala specificamente per il workspace dell'integrazione, a meno che non siano necessari più workspace.
4. Distribuisci la nuova chiave. Sostituisci la vecchia chiave ovunque l'integrazione la legga, tipicamente la variabile d'ambiente ANTHROPIC_API_KEY o una voce del secrets manager. Per una chiave multi-workspace, invia anche l'header anthropic-workspace-id come mostrato in Seleziona un workspace.
5. Elimina la vecchia chiave. Verifica che le richieste abbiano esito positivo, quindi elimina la chiave di workspace nella pagina API keys.

Workload Identity Federation

"Workload Identity Federation" (federazione delle identità dei workload), o WIF, consente a un workload di autenticarsi con un token di identità a breve durata rilasciato da un "identity provider" (provider di identità), o IdP, di cui già ti fidi, come AWS IAM, Google Cloud o qualsiasi issuer OIDC conforme agli standard (come GitHub Actions, service account Kubernetes, SPIFFE, Microsoft Entra ID o Okta). Il workload scambia il proprio JWT rilasciato dall'IdP presso POST /v1/oauth/token con un token di accesso alla Claude API a breve durata, e l'SDK aggiorna automaticamente quel token prima che scada. Non c'è alcuna stringa sk-ant-api... da generare, distribuire o ruotare.

La federazione rimuove le chiavi Claude API a lunga durata dal tuo ambiente, il che riduce il raggio d'impatto di una credenziale compromessa e ti permette di gestire l'accesso con gli stessi controlli IdP che già usi per le risorse cloud. Di per sé non garantisce la sicurezza end-to-end: la catena di fiducia è forte solo quanto la configurazione del tuo identity provider, e un segreto a lunga durata un passo più a monte (ad esempio, una credenziale cloud statica in grado di generare token IdP) può comunque comprometterla. Abbina la federazione ai controlli del tuo provider, come allowlist di IP, MFA e audit logging.

Per configurare la federazione, crei tre risorse nella Claude Console (un service account, un federation issuer e una federation rule) e poi punti il tuo SDK alla regola. Consulta Workload Identity Federation per la procedura di configurazione completa.

App Attest

App Attest autentica le app iOS e macOS che chiamano la Claude API direttamente dal dispositivo. Ogni installazione dimostra di essere una build autentica e non modificata di un'app che hai registrato nella Claude Console, usando il servizio App Attest di Apple. Anthropic rilascia quindi al dispositivo un token di accesso a breve durata che addebita l'utilizzo al tuo workspace. I token sono limitati al tuo workspace, scadono dopo un'ora e autorizzano solo le chiamate alla Messages API.

Per registrare la tua app e ottenere un client ID, consulta App Attest per app iOS e macOS.

Passaggi successivi