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 basate sull'identità: ognuna appartiene a un utente o service account che la tua organizzazione gestisce già, 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 sopravvivono 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 Chiavi API (platform.claude.com/settings/keys) e fai clic su Create key. Assegna un nome alla chiave e seleziona 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 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 l'SDK client la rileva 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 stata divulgata. Nella pagina 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 appare 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 divulgata 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 vedere come impostare questo header in una richiesta o nell'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 non limitata a un workspace.
# Ometti extra_headers per una chiave limitata a un solo workspace.
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": "This API key is not scoped to a workspace, so this request must include the anthropic-workspace-id header with the ID of the workspace to use. Add the header, or use an API key that is scoped to a workspace."
  },
  "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 Chiavi API 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 gestore di segreti 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 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 in seguito. 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 il riferimento WIF per i dettagli sulla configurazione della Workload Identity Federation, preferibile rispetto 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) nella Claude Console e di aggiungerlo al workspace pertinente.
3. Crea la nuova chiave. Creala specificamente per il workspace dell'integrazione, a meno che l'integrazione non necessiti di 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 di un gestore di segreti. Per una chiave non limitata a un 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

La Workload Identity Federation (WIF) consente a un carico di lavoro di autenticarsi con un identity token di breve durata emesso da un "identity provider" (provider di identità), o IdP, di cui già ti fidi. Tali IdP includono AWS IAM, Google Cloud e qualsiasi emittente OIDC conforme agli standard (come GitHub Actions, service account di Kubernetes, SPIFFE, Microsoft Entra ID o Okta). Il carico di lavoro scambia il proprio JWT emesso dall'IdP su POST /v1/oauth/token con un token di accesso di breve durata per l'API Claude, 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 Claude di lunga durata dal tuo ambiente, il che limita i danni che una credenziale divulgata può causare e ti consente di gestire l'accesso con gli stessi controlli IdP che già usi per le risorse cloud. Da sola, tuttavia, non garantisce la sicurezza end-to-end: la catena di fiducia è solida solo quanto la configurazione del tuo provider di identità, e un segreto di lunga durata in un anello precedente di quella catena (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 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 Claude direttamente dal dispositivo. Ogni installazione dimostra di essere una build autentica 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 1 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