--- title: Autenticazione url: https://platform.claude.com/docs/it/manage-claude/authentication description: Autenticati all'API di Claude con chiavi API, Workload Identity Federation o App Attest. --- L'API di Claude supporta tre modi per autenticare le richieste: | Metodo | Credenziale | Ideale per | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [Chiave API](https://platform.claude.com/docs/it/manage-claude/authentication#api-keys) | Segreto statico `sk-ant-api...` inviato come bearer token nell'header `Authorization` | Sviluppo locale, prototipazione, script e server dove controlli l'archiviazione dei segreti | | [Workload Identity Federation](https://platform.claude.com/docs/it/manage-claude/authentication#workload-identity-federation) | Bearer token di breve durata scambiato dal token di identità del tuo provider di identità | Carichi di lavoro in produzione su piattaforme cloud (AWS, Google Cloud, Azure), pipeline CI/CD e Kubernetes, dove vuoi eliminare i segreti statici | | [App Attest](https://platform.claude.com/docs/it/manage-claude/authentication#app-attest) | Token di accesso di breve durata emesso a un'installazione genuina e attestata della tua app iOS o macOS registrata | App iOS e macOS distribuite agli utenti finali, dove l'app chiama direttamente l'API di Claude senza back end o proxy | 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: | Tipo di chiave | Agisce come | Funziona in | Smette di funzionare quando | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Chiave personale** | Te, l'utente, con i tuoi ruoli e permessi | Un singolo workspace oppure i workspace in cui il tuo ruolo consente l'uso dell'API, scelti al momento della creazione della chiave | Perdi l'accesso all'organizzazione. Una chiave per singolo workspace smette di funzionare anche quando perdi l'accesso a quel workspace o quel workspace viene archiviato. Le chiavi personali vengono archiviate quando vieni rimosso dall'organizzazione. Se vieni invitato di nuovo, crea nuove chiavi; le chiavi archiviate non vengono ripristinate | | **Chiave di service account** | Un [service account](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation#service-accounts) | Un singolo workspace oppure qualsiasi cosa a cui il service account ha accesso, scelto al momento della creazione della chiave. Un service account ha accesso al Default Workspace e ai workspace a cui è stato aggiunto | Il service account viene archiviato. Una chiave per singolo workspace smette di funzionare anche quando il service account viene rimosso da quel workspace o quel workspace viene archiviato | | **Chiave di workspace** (legacy) | Nessuno: appartiene al workspace in cui è stata creata | Quel workspace | Scade, viene disabilitata o eliminata, o il suo workspace viene archiviato, indipendentemente dal fatto che il suo creatore lasci l'organizzazione | 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](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation). Per migrare, consulta [Sostituire le chiavi API di workspace](https://platform.claude.com/docs/it/manage-claude/authentication#replacing-workspace-api-keys). ### Creare e usare una chiave * **Crea una chiave:** Nella Claude Console, vai alla pagina [Chiavi API](https://platform.claude.com/settings/keys) (`platform.claude.com/settings/keys`) e fai clic su **Create key**. Assegna un nome alla chiave e seleziona una [scadenza](https://platform.claude.com/docs/it/manage-claude/authentication#key-expiration). 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 ` nelle richieste HTTP dirette, oppure imposta la variabile d'ambiente `ANTHROPIC_API_KEY` e l'[SDK client](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) la rileva automaticamente. ```http 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](https://platform.claude.com/settings/keys) 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](https://platform.claude.com/docs/it/api/organization/api_keys/list) con `status: "archived"`. Le chiavi scadute possono solo essere eliminate. Puoi anche impostare una [scadenza](https://platform.claude.com/docs/it/manage-claude/authentication#key-expiration) quando crei una chiave per limitare per quanto tempo una credenziale divulgata rimane utilizzabile. ```bash cURL 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": "claude-opus-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```bash CLI # Vedi /docs/en/cli-sdks-libraries/cli/authentication#api-key per le varianti zsh, bash e Windows export ANTHROPIC_API_KEY=sk-ant-api03-... ``` ```python Python client = Anthropic(api_key="my-anthropic-api-key") # oppure, con ANTHROPIC_API_KEY impostata nell'ambiente: client = Anthropic() ``` ```typescript TypeScript const client = new Anthropic({ apiKey: "my-anthropic-api-key" }); // oppure, con ANTHROPIC_API_KEY impostata nell'ambiente: // const client = new Anthropic(); ``` ```csharp C# using Anthropic; AnthropicClient client = new() { ApiKey = "my-anthropic-api-key" }; // Oppure, con ANTHROPIC_API_KEY impostata nell'ambiente: // AnthropicClient client = new(); ``` ```go Go client := anthropic.NewClient( option.WithAPIKey("sk-ant-api03-..."), // defaults to os.LookupEnv("ANTHROPIC_API_KEY") ) ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; // Esplicito AnthropicClient client = AnthropicOkHttpClient.builder() .apiKey("my-anthropic-api-key") .build(); // Da ANTHROPIC_API_KEY (o proprietà di sistema anthropic.apiKey) AnthropicClient clientFromEnv = AnthropicOkHttpClient.fromEnv(); ``` ```php PHP // Legge ANTHROPIC_API_KEY dall'ambiente $client = new Client(); // Oppure passa la chiave esplicitamente: $client = new Client(apiKey: 'my-anthropic-api-key'); ``` ```ruby Ruby anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") # oppure, con ANTHROPIC_API_KEY impostata nell'ambiente: anthropic = Anthropic::Client.new ``` ### 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](https://platform.claude.com/docs/it/manage-claude/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](https://platform.claude.com/settings/workspaces) (`platform.claude.com/settings/workspaces`) nella Claude Console, oppure chiamando l'endpoint [List Workspaces](https://platform.claude.com/docs/it/api/organization/workspaces/list). List Workspaces include il Default Workspace solo quando passi `include_default=true`; il suo ID si trova anche nell'[header di risposta](https://platform.claude.com/docs/it/manage-claude/workspaces#identify-the-workspace-behind-an-api-response) `anthropic-workspace-id` di qualsiasi richiesta eseguita lì. ```bash cURL # Obbligatorio in ogni richiesta per una chiave non limitata a un workspace. # Ometti l'header anthropic-workspace-id per una chiave limitata a un solo workspace. curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```bash CLI # Obbligatorio in ogni comando per una chiave non limitata a un workspace. # Ometti --workspace-id per una chiave limitata a un singolo workspace. ant messages create \ --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \ --model claude-opus-5-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` ```python Python 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"}, ) ``` ```typescript TypeScript const client = new Anthropic(); // reads ANTHROPIC_API_KEY // Obbligatorio in ogni richiesta per una chiave non limitata a un workspace. // Ometti il secondo argomento per una chiave limitata a un solo workspace. const message = await client.messages.create( { model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }, { headers: { "anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } } ); console.log(message.content); // Oppure impostalo una volta per ogni richiesta da questo client: const workspaceClient = new Anthropic({ defaultHeaders: { "anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } }); ``` ```csharp C# AnthropicClient client = new(); // reads ANTHROPIC_API_KEY MessageCreateParams parameters = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [new UserMessageParam { Content = "Hello, Claude" }], }; // Obbligatorio in ogni richiesta per una chiave non limitata a un workspace. // Chiama direttamente client.Messages.Create(parameters) per una chiave limitata a un solo workspace. var message = await client .WithOptions(options => options with { ExtraHeaders = new Dictionary { ["anthropic-workspace-id"] = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", }, } ) .Messages.Create(parameters); Console.WriteLine(message); // Oppure impostalo una volta per ogni richiesta da questo client: AnthropicClient workspaceClient = new(new ClientOptions { ExtraHeaders = new Dictionary { ["anthropic-workspace-id"] = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", }, }); ``` ```go Go client := anthropic.NewClient() // reads ANTHROPIC_API_KEY // Obbligatorio in ogni richiesta per una chiave non limitata a un workspace. // Ometti l'opzione per una chiave limitata a un solo workspace. message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }, option.WithHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")) if err != nil { log.Fatal(err) } fmt.Println(message.Content) // Oppure impostalo una volta per ogni richiesta da questo client: workspaceClient := anthropic.NewClient( option.WithHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"), ) ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // reads ANTHROPIC_API_KEY // Obbligatorio in ogni richiesta per una chiave non limitata a un workspace. // Ometti putAdditionalHeader per una chiave limitata a un solo workspace. Message message = client.messages().create(MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .putAdditionalHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ") .build()); IO.println(message.content()); // Oppure impostalo una volta per ogni richiesta da questo client: AnthropicClient workspaceClient = AnthropicOkHttpClient.builder() .fromEnv() .putHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ") .build(); ``` ```php PHP $client = new Client(); // reads ANTHROPIC_API_KEY // Obbligatorio in ogni richiesta per una chiave non limitata a un workspace. // Ometti requestOptions per una chiave limitata a un singolo workspace. $message = $client->messages->create( model: Model::CLAUDE_OPUS_5_5, maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], requestOptions: [ 'extraHeaders' => ['anthropic-workspace-id' => 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'], ], ); echo json_encode($message->content), PHP_EOL; ``` ```ruby Ruby client = Anthropic::Client.new # reads ANTHROPIC_API_KEY # Obbligatorio in ogni richiesta per una chiave non limitata a un workspace. # Ometti request_options per una chiave limitata a un solo workspace. message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], request_options: {extra_headers: {"anthropic-workspace-id" => "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"}} ) puts message.content ``` Se una richiesta effettuata con una chiave non limitata a un workspace omette l'header, l'API restituisce un `invalid_request_error` 400: ```json JSON { "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 `` 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](https://platform.claude.com/docs/it/manage-claude/wif-reference) per i dettagli. ### Scadenza della chiave Quando crei una chiave API dalla pagina [Chiavi API](https://platform.claude.com/settings/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 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](https://platform.claude.com/docs/it/manage-claude/admin-api-keys) 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](https://platform.claude.com/docs/it/api/organization/api_keys/list) e [Retrieve API Key](https://platform.claude.com/docs/it/api/organization/api_keys/retrieve), 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](https://platform.claude.com/docs/it/manage-claude/wif-reference) o con una chiave personale o di service account. Questo fornisce una migliore sicurezza e osservabilità. Consulta il [riferimento WIF](https://platform.claude.com/docs/it/manage-claude/wif-reference) 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](https://platform.claude.com/settings/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](https://platform.claude.com/docs/it/manage-claude/authentication#select-a-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](https://platform.claude.com/settings/keys) 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](https://platform.claude.com/docs/it/manage-claude/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](https://platform.claude.com/docs/it/api/messages/create). Per registrare la tua app e ottenere un client ID, consulta [App Attest per app iOS e macOS](https://platform.claude.com/docs/it/manage-claude/app-attest). ## Prossimi passi Configura emittenti, regole e service account, poi scambia i token Guide passo passo per AWS, Google Cloud, Azure, GitHub Actions, Kubernetes, SPIFFE e Okta Variabili d'ambiente, regole di validazione, configurazione del profilo e riferimento agli errori Consenti alle installazioni genuine della tua app di chiamare l'API di Claude senza distribuire una chiave API Python, TypeScript, C#, Go, Java, PHP, Ruby e la CLI