Workspace

I workspace offrono un modo per organizzare l’utilizzo dell’API all’interno di un’organizzazione. Usa i workspace per separare progetti, ambienti o team diversi mantenendo al contempo fatturazione e amministrazione centralizzate.

Come funzionano i workspace

Ogni organizzazione ha un workspace predefinito che non può essere rinominato, archiviato o eliminato. Quando crei workspace aggiuntivi, puoi assegnare membri, account di servizio, chiavi API e limiti di risorse a ciascuno di essi.

Caratteristiche principali:

• Gli identificatori dei workspace usano il prefisso wrkspc_ (ad esempio, wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ).
• Massimo 100 workspace per ogni organizzazione per impostazione predefinita (i workspace archiviati non vengono conteggiati). Contatta il tuo team account se te ne servono di più.
• Il workspace predefinito ha un ID wrkspc_ come qualsiasi altro workspace (restituito nell’header di risposta anthropic-workspace-id e accettato da Ottieni workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro)), ma compare nei risultati di Elenca i workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) solo quando passi include_default=true. L’API Usage and Cost Analytics riporta il suo utilizzo e il suo costo sotto quell’ID, mentre i report dell’API Usage and Cost legacy mostrano null per il suo workspace_id (il campo scope di una chiave API contiene l’ID reale per una chiave associata al workspace predefinito).
• Le chiavi API possono essere limitate a un singolo workspace. In questo caso, possono accedere solo alle risorse all’interno di quel workspace. Altre chiavi API non sono limitate a un workspace. Con una di queste chiavi, invia un header dell’ID del workspace in ogni richiesta per scegliere il workspace. L’utente o l’account di servizio della chiave deve avere accesso a quel workspace.

Workspace Claude Code

Quando un membro della tua organizzazione accede per la prima volta a Claude Code con il proprio account Claude Console, Anthropic crea automaticamente un workspace Claude Code nell’organizzazione e aggiunge quel membro ad esso. Ogni membro successivo che accede a Claude Code viene aggiunto allo stesso modo.

Il workspace Claude Code mantiene il traffico di Claude Code separato dagli altri carichi di lavoro API:

• Claude Code genera una chiave API per utente in questo workspace al momento dell’accesso. Non puoi creare chiavi in esso manualmente dalla Console.
• Una chiave Claude Code smette di funzionare se il suo proprietario viene rimosso dal workspace o dall’organizzazione, a differenza di una chiave del workspace.
• L’utilizzo di Claude Code ha un “rate limit” (limite di velocità) separato, e gli amministratori possono limitarne la quota sui limiti dell’organizzazione in Limiti di richieste nella Claude Console.
• È l’unico workspace che supporta limiti di spesa mensili per utente.

Ruoli e permessi dei workspace

I membri possono avere ruoli diversi in ciascun workspace, consentendo un controllo degli accessi granulare.

Ereditarietà dei ruoli

• Gli amministratori dell’organizzazione ricevono automaticamente l’accesso di Amministratore dell’area di lavoro a tutti i workspace.
• I membri di fatturazione dell’organizzazione ricevono automaticamente l’accesso di Fatturazione dell’area di lavoro a tutti i workspace.
• Gli utenti e gli sviluppatori dell’organizzazione devono essere aggiunti esplicitamente a ciascun workspace.
• Gli account di servizio vengono aggiunti ai workspace nella pagina Account di servizio (platform.claude.com/settings/service-accounts) della Claude Console: seleziona Aggiungi all’area di lavoro nel menu dell’account o nella sua pagina. Per vedere gli account in un workspace, filtra l’elenco per workspace.

Gestione dei workspace

Utilizzo della Console

Crea e gestisci i workspace nella pagina Aree di lavoro della Claude Console.

Crea un workspace

1. 1

   Apri le impostazioni dei workspace

   Nella Claude Console, vai alla pagina Aree di lavoro (platform.claude.com/settings/workspaces).

2. 2

   Apri la pagina Crea area di lavoro

   Fai clic su Crea area di lavoro per aprire la pagina Crea area di lavoro (platform.claude.com/settings/workspaces/new) nella Console.

3. 3

   Configura il workspace

   Inserisci un nome per il workspace e seleziona un colore per l’identificazione visiva.

4. 4

   Crea il workspace

   Fai clic su Crea area di lavoro per completare.

Modifica i dettagli del workspace

Per modificare il nome o il colore di un workspace:

1. Seleziona il workspace dall’elenco.
2. Apri il menu Altre azioni (tre puntini) e seleziona Modifica dettagli.
3. Aggiorna il nome o il colore e salva le modifiche.

Aggiungi membri a un workspace

1. Nella Claude Console, vai alla pagina Membri (platform.claude.com/settings/members).
2. Fai clic su Aggiungi all’area di lavoro.
3. Seleziona il workspace, il membro dell’organizzazione da aggiungere e il suo ruolo nel workspace.
4. Fai clic su Aggiungi all’area di lavoro per confermare.

Rimuovi membri da un workspace

1. Nella pagina Membri della Claude Console, seleziona il workspace dal menu a discesa Area di lavoro. Se mostra Tutti, Rimuovi membro rimuove invece il membro dalla tua organizzazione.
2. Alla fine della riga del membro, apri il menu Altre azioni (tre puntini) e seleziona Rimuovi membro.
3. Fai clic su Rimuovi per confermare.

Imposta i limiti del workspace

I limiti di velocità e i limiti di spesa di un workspace si impostano in posti diversi:

• Limiti di velocità: In Limiti di richieste nella Claude Console, seleziona il workspace dal menu a discesa Area di lavoro e fai clic su Modifica accanto a un modello per impostare i limiti per richieste al minuto, token di input o token di output.
• Limiti di spesa: Nella pagina Aree di lavoro della Claude Console, seleziona il workspace. Nel pannello che si apre, fai clic su Limiti di spesa per limitare la spesa mensile e configurare avvisi quando la spesa raggiunge determinate soglie.

Archivia un workspace

Per archiviare un workspace, apri il suo menu Altre azioni (tre puntini) e seleziona Archivia area di lavoro. L’archiviazione:

• Conserva i dati storici per la reportistica
• Disattiva il workspace e archivia ogni chiave API creata per esso
• Non può essere annullata

Utilizzo dell’Admin API

Gestisci i workspace in modo programmatico utilizzando l’Admin API.

I seguenti esempi di SDK e CLI costruiscono il client predefinito, che legge la chiave Admin API dalla variabile d’ambiente ANTHROPIC_API_KEY; l’SDK espone questi endpoint sotto client.organization.workspaces. I metodi di elenco dell’SDK recuperano ulteriori pagine su richiesta, quindi limit imposta la dimensione della pagina; gli esempi PHP, Ruby e curl restituiscono una sola pagina.

Crea un workspace:

client = anthropic.Anthropic()

workspace = client.organization.workspaces.create(name="Production")

print(f"id: {workspace.id}")
print(f"name: {workspace.name}")

Elenca i workspace:

client = anthropic.Anthropic()

workspaces = client.organization.workspaces.list(limit=10, include_archived=False)

for workspace in workspaces:
    print(f"{workspace.id}: {workspace.name}")

Archivia un workspace:

client = anthropic.Anthropic()

workspace = client.organization.workspaces.archive("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")

print(f"id: {workspace.id}")
print(f"archived_at: {workspace.archived_at}")

Per i dettagli completi sui parametri e gli schemi di risposta, consulta il riferimento dell’API WorkspacesAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro).

Gestione dei membri del workspace

Aggiungi un membro a un workspace:

client = anthropic.Anthropic()

member = client.organization.workspaces.members.add(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    user_id="user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_role="workspace_developer",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

Aggiorna il ruolo di un membro:

client = anthropic.Anthropic()

member = client.organization.workspaces.members.update(
    "user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    workspace_role="workspace_admin",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

Rimuovi un membro da un workspace:

client = anthropic.Anthropic()

removed_member = client.organization.workspaces.members.remove(
    "user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

print(f"user_id: {removed_member.user_id}")

Per i dettagli completi sui parametri, consulta il riferimento dell’API dei membri del workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro).

Chiavi API e ambito delle risorse

Ogni richiesta viene eseguita in esattamente un workspace e può accedere solo alle risorse all’interno di quel workspace. Quale workspace dipende dal tipo di chiave:

• Una chiave del workspace (una chiave legacy senza proprietario) appartiene al workspace in cui è stata creata e viene sempre eseguita lì.
• Una chiave personale o una chiave di account di servizio agisce come il proprio utente o account di servizio. Una chiave a workspace singolo viene sempre eseguita nel workspace scelto al momento della sua creazione. Una chiave non limitata a un workspace viene eseguita nel workspace indicato dall’header anthropic-workspace-id di ciascuna richiesta. Gli account devono avere accesso al workspace per usarlo.

Le risorse limitate ai workspace includono:

• File creati tramite l’API Files
• Batch di messaggi creati tramite l’API Batch
• Skills create tramite l’API Skills

Alcune risorse vengono gestite in modo diverso:

• I tunnel MCP vengono gestiti con un token OAuth workspace:manage_tunnels ottenuto tramite Workload Identity Federation, non una chiave API. I tunnel vengono creati in un workspace, e l’elenco Tunnel MCP della Console e il selettore del server Managed Agent mostrano solo i tunnel nel workspace corrente; il limite di 10 tunnel attivi si applica a livello di organizzazione. La gestione dei tunnel richiede un ruolo con permessi di gestione dei tunnel; gli sviluppatori dell’organizzazione possono visualizzarli ma non modificarli.
• I workspace stessi e i membri dell’organizzazione vengono gestiti a livello di organizzazione tramite l’Admin API, utilizzando una chiave Admin API, un token OAuth org:admin, o una chiave personale o di account di servizio che non sia limitata a un workspace specifico.

Per trovare gli ID dei workspace della tua organizzazione, chiama l’endpoint Elenca i workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) (passa include_default=true per includere il workspace predefinito) oppure trovali nella pagina Aree di lavoro della Claude Console.

Identifica il workspace dietro una risposta API

Le risposte dell’API Claude includono un header anthropic-workspace-id insieme agli header di risposta request-id e anthropic-organization-id. Il suo valore è l’ID con prefisso wrkspc_ del workspace a cui la chiave API o il token di accesso della richiesta è stato risolto, incluso quando quel workspace è il workspace predefinito. Ad esempio, una risposta riuscita include header come questi:

HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

L’header è assente quando la credenziale non si risolve in un workspace (ad esempio, nelle richieste dell’Admin API) o quando la richiesta fallisce prima del completamento dell’autenticazione, come un errore 401.

I seguenti esempi inviano una richiesta all’API Messages e leggono l’ID del workspace dagli header di risposta:

client = anthropic.Anthropic()

response = client.messages.with_raw_response.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
workspace_id = response.headers.get("anthropic-workspace-id")
print(f"Workspace ID: {workspace_id}")

Workspace ID: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

Gli stessi accessor leggono l’header anche da altri endpoint dell’API Claude, incluse le API Claude Managed Agents. Ad esempio, leggi anthropic-workspace-id dalla risposta che crea una sessione per registrare a quale workspace appartiene la sessione.

Con l’ID del workspace da una risposta, puoi:

• Confermare a quale utilizzo, costo e limiti di velocità del workspace è stata conteggiata la richiesta
• Confrontarlo con il campo workspace_id nelle righe dell’API Usage and Cost Analytics, che riportano questo stesso ID per il workspace predefinito, e con il campo scope delle chiavi API nell’Admin API, che contiene l’ID reale del workspace a cui è associata una chiave, incluso il workspace predefinito
• Verificare se si tratta dell’ID del tuo workspace predefinito passandolo a Ottieni workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) con una chiave Admin API: il workspace predefinito viene restituito con "name": "Default", anche se Elenca i workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) lo omette a meno che tu non passi include_default=true
• Aprire quel workspace nella Console per trovare le risorse della richiesta, come sessioni, file, batch di messaggi e skill

Limiti del workspace

Puoi impostare limiti di spesa e di velocità personalizzati per ciascun workspace per proteggerti dall’uso eccessivo e garantire una distribuzione equa delle risorse.

Impostazione dei limiti del workspace

Puoi impostare limiti del workspace inferiori (ma non superiori) ai limiti della tua organizzazione:

• Limiti di spesa: Limita la spesa mensile di un workspace. Per impostarli, vai alla pagina Aree di lavoro (platform.claude.com/settings/workspaces) nella Claude Console e seleziona il workspace. Nel pannello che si apre, fai clic su Limiti di spesa.
• Limiti di velocità: Limita le richieste al minuto, i token di input al minuto o i token di output al minuto. Per impostarli, vai a Limiti di richieste nella Claude Console, seleziona il workspace dal menu a discesa Area di lavoro e fai clic su Modifica accanto a un modello.

Per informazioni dettagliate sui “rate limit” (limiti di velocità) e sul loro funzionamento, consulta Limiti di velocità. Puoi anche leggere i limiti di velocità attuali della tua organizzazione e del tuo workspace e impostare i limiti di velocità del workspace in modo programmatico con l’API Rate Limits, che memorizza un valore superiore al limite dell’organizzazione ma applica comunque il più basso dei due.

Tracciamento dell’utilizzo e dei costi

Traccia l’utilizzo e i costi per workspace usando l’API Usage and Cost Analytics:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    group_by=["workspace_id"],
)

for row in rows:
    print(f"{row.starting_at} {row.group.workspace_id}: {row.usage.total_tokens}")

L’utilizzo e i costi nel workspace predefinito vengono riportati con l’ID proprio del workspace predefinito.

Casi d’uso comuni

Separazione degli ambienti

Crea workspace separati per sviluppo, staging e produzione:

Isolamento di team o reparti

Assegna i workspace a team diversi per l’allocazione dei costi e il controllo degli accessi:

• Team di ingegneria con accesso sviluppatore
• Team di data science con le proprie chiavi API
• Team di supporto con accesso limitato per gli strumenti dei clienti

Organizzazione basata sui progetti

Crea workspace per progetti o prodotti specifici per tracciare l’utilizzo e i costi separatamente.

Best practice

1. 1

   Pianifica la struttura del tuo workspace

   Considera come organizzerai i workspace prima di crearli. Pensa alle esigenze di fatturazione, controllo degli accessi e tracciamento dell’utilizzo.

2. 2

   Usa nomi significativi

   Assegna nomi chiari ai workspace per indicarne lo scopo (ad esempio, “Production - Customer Chatbot” o “Dev - Internal Tools”).

3. 3

   Imposta limiti appropriati

   Configura i limiti di spesa e di velocità per prevenire costi imprevisti e garantire una distribuzione equa delle risorse.

4. 4

   Verifica regolarmente gli accessi

   Rivedi periodicamente l’appartenenza ai workspace per assicurarti che solo gli utenti appropriati abbiano accesso.

5. 5

   Monitora l’utilizzo

   Usa l’API Usage and Cost Analytics per monitorare il consumo a livello di workspace.

Domande frequenti

Vedi anche

• Admin API
• Riferimento dell’Admin API
• Limiti di velocità
• API Usage and Cost Analytics e l’API Usage and Cost legacy