Autenticazione

L'API di Claude supporta tre modi per autenticare le richieste:

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

Chiavi API

Le chiavi API sono segreti statici che generi nella Claude Console e invii a ogni richiesta come bearer token nell'header Authorization.

Tipi di chiave

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

Le chiavi personali e le chiavi di service account sono supportate da 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. Questo significa che le chiavi non sopravvivranno accidentalmente alle persone o ai carichi di lavoro 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 si interrompe quando questa se ne va. Per carichi di lavoro condivisi o automatizzati (CI, servizi di produzione), fai creare a un amministratore dell'organizzazione un service account in modo che il carico di lavoro abbia la propria identità.

Le chiavi API di workspace funzionano ancora ma dovrebbero essere considerate legacy; sono preferibili le chiavi supportate da un'identità o Workload Identity Federation. Per migrare, consulta Sostituire le chiavi API di workspace.

Creare e usare una chiave

• Crea una chiave: Nella Claude Console, vai alla pagina API keys (platform.claude.com/settings/keys) 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 consente di evitare di impostare manualmente un ID workspace nelle richieste future.
• Usa la chiave: Inviala come Authorization: Bearer <key> nelle richieste HTTP dirette, oppure imposta la variabile d'ambiente ANTHROPIC_API_KEY e gli SDK client la rileveranno automaticamente.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

L'header legacy x-api-key: YOUR_API_KEY è ancora supportato al posto di Authorization.

Archivia le chiavi API in un gestore di segreti, ruotale periodicamente e disabilita o elimina qualsiasi chiave che sospetti sia trapelata. Nella pagina delle chiavi API della Claude Console, 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 per quanto tempo una credenziale trapelata rimane utilizzabile.

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

Selezionare 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 workspace.

Se la tua chiave API non è limitata a un workspace, devi specificare l'ID workspace nell'header anthropic-workspace-id per ogni richiesta. Consulta l'esempio seguente per sapere 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 della pagina Workspaces (platform.claude.com/settings/workspaces) nella Claude Console, oppure chiamando l'endpoint List Workspaces. List Workspaces include il Default Workspace solo quando passi include_default=true; il suo ID si trova anche nell'header di risposta anthropic-workspace-id di qualsiasi richiesta eseguita lì.

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-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 invalid_request_error 400:

{
  "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 di header che non è un ID workspace valido restituisce un invalid_request_error 400 con il messaggio anthropic-workspace-id header must be a valid workspace ID. Se il workspace non esiste, o l'utente o il service account della chiave non vi ha accesso, l'API restituisce un not_found_error 404 con il messaggio Workspace `<id>` not found., la stessa risposta che si ottiene per qualsiasi workspace sconosciuto.

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

Scadenza della chiave

Quando crei una chiave API dalla pagina delle chiavi API nella Claude Console, scegli una scadenza: un preset (3 ore, 1 giorno, 7 giorni o 30 giorni), una durata personalizzata, o Never per le chiavi che archivi in un gestore di segreti e ruoti autonomamente. Se la tua organizzazione ha una policy di scadenza massima, la Console limita i preset e le durate personalizzate al massimo della 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 un'email di avviso.

Dopo che una chiave scade, 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 ciascuna chiave, e l'Admin API riporta il timestamp expires_at di ciascuna 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 trapelata, ma non sostituisce una buona igiene dei segreti. Indipendentemente dalla scadenza, archivia le chiavi in un gestore di segreti e disabilita o elimina qualsiasi chiave che sospetti sia trapelata.

Sostituire le chiavi API di workspace

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

Consulta Workload Identity Federation per i dettagli sulla configurazione di Workload Identity Federation, che è preferibile alle chiavi di 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 dovrebbero usare una chiave personale. Un carico di lavoro 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 nella pagina Service accounts (platform.claude.com/settings/service-accounts) della Claude Console 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 gestore di segreti. Per una chiave multi-workspace, invia anche l'header anthropic-workspace-id come mostrato in Selezionare un workspace.
5. Elimina la vecchia chiave. Verifica che le richieste vadano a buon fine, quindi elimina la chiave di workspace nella pagina delle chiavi API della Claude Console.

Workload Identity Federation

Workload Identity Federation (WIF) consente a un carico di lavoro di autenticarsi con un token di identità di breve durata emesso da un provider di identità (IdP) di cui ti fidi già, come AWS IAM, Google Cloud, o qualsiasi emittente OIDC conforme agli standard (come GitHub Actions, service account Kubernetes, SPIFFE, Microsoft Entra ID o Okta). Il carico di lavoro scambia il suo JWT emesso dall'IdP su POST /v1/oauth/token per un token di accesso all'API di Claude di 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 API di Claude di lunga durata dal tuo ambiente, il che riduce il raggio d'azione di una credenziale trapelata e ti consente di gestire l'accesso con gli stessi controlli IdP che già usi per le risorse cloud. Non garantisce, di per sé, una sicurezza end-to-end: la catena di fiducia è forte solo quanto la configurazione del tuo provider di identità, e un segreto di lunga durata a un passo a monte (ad esempio, una credenziale cloud statica che può 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 emittente di federazione e una regola di federazione) e poi indirizzi il tuo SDK alla regola. Consulta Workload Identity Federation per la guida completa alla configurazione.

App Attest

App Attest autentica le app iOS e macOS che chiamano l'API di Claude direttamente dal dispositivo. Ogni installazione dimostra di essere una build genuina e non modificata di un'app che hai registrato nella Claude Console, utilizzando il servizio App Attest di Apple. Anthropic emette quindi al dispositivo un token di accesso di 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.

Prossimi passi