Tre credenziali, non una

L’API Claude accetta tre modi di autenticarsi. Una chiave API è un segreto statico che generi in Console e invii nell’header x-api-key. Workload Identity Federation scambia l’identity token del tuo identity provider con un access token Anthropic di breve durata. App Attest rilascia un token corto a un’installazione attestata della tua app iOS o macOS, per quando l’app chiama l’API senza back end né proxy.

Chiave e federazione concedono lo stesso accesso agli endpoint: cambia il ciclo di vita del segreto, non l’autorizzazione. Chiave per sviluppo locale, script e server dove controlli tu la conservazione; federazione quando il carico ha già un’identità emessa dalla piattaforma su cui gira.

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

Gli SDK leggono ANTHROPIC_API_KEY dall’ambiente da soli, così il client si costruisce senza argomenti. È comodo, ed è anche la trappola descritta più avanti.

Chiavi legate a un’identità, e al workspace giusto

Alla creazione scegli il tipo di chiave, e il tipo decide dove funziona e quando smette di funzionare. Una personal key agisce come te, con i tuoi ruoli. Una service account key agisce come un account di servizio: è l’identità da usare per CI e servizi condivisi. La workspace key esiste ancora, ma è legacy e non appartiene a nessuno. Il motivo per preferire le prime due è dichiarato: «This means that keys won’t accidentally outlive the people or workloads that own them.» Una chiave personale condivisa nel team agisce come una sola persona, e si rompe quando quella persona esce.

Seconda decisione: lo scope. Una chiave creata per un workspace specifico funziona solo lì, e le richieste possono omettere l’ID. Una chiave non vincolata a un workspace obbliga a mandare anthropic-workspace-id a ogni richiesta; senza, arriva un 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."
  }
}

La scadenza si sceglie alla creazione — preset da 3 ore a 30 giorni, durata custom, oppure «Never» — e non si cambia dopo. Una chiave scaduta risponde 401 authentication_error e non si riattiva. In Console «Disable» è reversibile, «Delete» no. Il resto è igiene: «Store API keys in a secrets manager, rotate them periodically, and disable or delete any key you suspect has leaked.»

Federazione: token corto al posto di segreto lungo

WIF toglie di mezzo la chiave: «There are no static secrets to mint, store in CI, rotate, or leak.» Configuri tre risorse: un service account, che è l’identità di destinazione; un federation issuer, cioè l’IdP di cui accetti le firme, con JWKS via discovery, URL esplicita o inline; e una federation rule, che porta le condizioni di match sulle claim, lo scope OAuth e la durata del token. A runtime il workload presenta il suo JWT a POST /v1/oauth/token con il grant jwt-bearer di RFC 7523, e l’SDK rinnova da solo.

Tre dettagli si pagano in produzione. La durata del token è il minore fra token_lifetime_seconds (default 3600) e il doppio della vita residua del JWT, mai sotto i 60 secondi. Il refresh è a due livelli: tentativo consigliato a scadenza meno 120 secondi, obbligatorio a meno 30. E i JWT con claim jti sono monouso, quindi un retry loop che ripresenta lo stesso token viene rifiutato con motivo jti_reused.

La trappola vera è la precedenza delle credenziali: «ANTHROPIC_API_KEY sits above the federation tiers, so a leftover key in the environment silently shadows federation.» Migrando un workload, la chiave vecchia continua a vincere in silenzio finché non la togli da container, secret di CI e profili di shell. Il comando ant auth status dice quale sorgente ha vinto: verificalo, non dare per buono che la federazione sia attiva perché è configurata.

Segreti di terze parti, e chi ha usato cosa

I segreti verso i servizi esterni sono un problema diverso dalla chiave Anthropic. Con i vault dei Managed Agents registri una credenziale per utente finale e la referenzi per ID alla creazione della sessione; per le variabili d’ambiente il sandbox riceve un placeholder opaco e la sostituzione avviene in uscita, quindi «The agent never sees the secret value.» Restringi sempre networking.allowed_hosts e lascia attiva la sola iniezione negli header, che è la configurazione più stretta. Due limiti: i vault sono workspace-scoped, quindi qualunque chiave con accesso a quel workspace può referenziarli, e «Substitution is outbound only» — se il client scambia il segreto per un token di sessione, quel token torna nel sandbox in chiaro.

Lato Claude Code le credenziali locali non stanno in un file di testo: «API keys and tokens are stored in the macOS Keychain when available, and protected by file permissions on Windows and Linux.» Un’organizzazione può forzare il metodo di login con forceLoginMethod, e in quel caso le sessioni autenticate da ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o apiKeyHelper vengono bloccate all’avvio.

Il monitoraggio va acceso a mano: la telemetria OpenTelemetry esporta attributi come user.account_uuid e organization.id, ed emette claude_code.auth quando /login o /logout si completa. Sul lato API, List API Keys riporta status ed expires_at di ogni chiave: mettilo in un job periodico, e ruoterai prima della scadenza invece che dopo il 401.