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 Default Workspace 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 organizzazione per impostazione predefinita (i workspace archiviati non vengono conteggiati); contatta il tuo account team se ne hai bisogno di più
• Il Default Workspace ha un ID wrkspc_ come qualsiasi altro workspace (restituito nell'header di risposta anthropic-workspace-id e accettato da Get Workspace), ma compare nei risultati di List Workspaces solo quando passi include_default=true, e le chiavi API, i report di utilizzo e i report dei costi mostrano null per il suo workspace_id, così come le chiavi API valide per tutti i workspace (il campo scope di una chiave API permette di distinguerle; per una chiave associata al Default Workspace contiene l'ID reale)
• Le chiavi API possono essere limitate a un singolo workspace. In questo caso, possono accedere solo alle risorse all'interno di quel workspace. Ad alcune chiavi API possono essere concessi permessi su più workspace, e forniscono un header dell'ID del workspace per accedere alle risorse all'interno di 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 è soggetto a limiti di velocità separati, e gli amministratori possono limitarne la quota rispetto ai limiti dell'organizzazione nella pagina Rate limits della 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 Workspace Admin a tutti i workspace
• I membri di fatturazione dell'organizzazione ricevono automaticamente l'accesso Workspace Billing a tutti i workspace
• Gli utenti e sviluppatori dell'organizzazione devono essere aggiunti esplicitamente a ciascun workspace
• Gli account di servizio vengono aggiunti ai workspace nella pagina Service accounts (platform.claude.com/settings/service-accounts) della Claude Console: seleziona Add to workspace 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 Claude Console.

Crea un workspace

1. 1

   Apri le impostazioni dei workspace

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

2. 2

   Apri la pagina Create workspace

   Fai clic su Create workspace per aprire la pagina Create workspace (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 Create workspace 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 More actions (tre puntini) e seleziona Edit details.
3. Aggiorna il nome o il colore e salva le modifiche.

Aggiungi membri a un workspace

1. Nella Claude Console, vai alla pagina Members (platform.claude.com/settings/members).
2. Fai clic su Add to workspace.
3. Seleziona il workspace, il membro dell'organizzazione da aggiungere e il suo ruolo nel workspace.
4. Fai clic su Add to workspace per confermare.

Rimuovi membri da un workspace

1. Nella pagina Members della Claude Console, seleziona il workspace dal menu a discesa Workspace. Se mostra All, Remove member rimuove invece il membro dalla tua organizzazione.
2. Alla fine della riga del membro, apri il menu More actions (tre puntini) e seleziona Remove member.
3. Fai clic su Remove 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à: Nella pagina Rate limits della Claude Console, seleziona il workspace dal menu a discesa Workspace e fai clic su Edit accanto a un modello per impostare i limiti per richieste al minuto, token di input o token di output.
• Limiti di spesa: Nella pagina Workspaces della Claude Console, seleziona il workspace. Nel pannello che si apre, fai clic su Spend limits 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 More actions (tre puntini) e seleziona Archive workspace. 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 SDK e CLI costruiscono il client predefinito, che legge la chiave Admin API dalla variabile d'ambiente ANTHROPIC_API_KEY; gli SDK espongono questi endpoint sotto client.organization.workspaces. I metodi di elenco degli SDK recuperano le pagine successive 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 Workspaces.

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_01XyDMpzjS89pFZXqSFUBDr6",
    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_01XyDMpzjS89pFZXqSFUBDr6",
    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_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

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

Per i dettagli completi sui parametri, consulta il riferimento dell'API Workspace Members.

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 suo utente o account di servizio. Una chiave a singolo workspace viene sempre eseguita nel workspace scelto al momento della sua creazione. Una chiave multi-workspace viene eseguita nel workspace indicato dall'header anthropic-workspace-id di ciascuna richiesta. Gli account devono avere accesso al workspace per poterlo utilizzare.

Le risorse limitate ai workspace includono:

• File creati tramite l'API Files
• Message Batches 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 MCP tunnels 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 List Workspaces (passa include_default=true per includere il Default Workspace) oppure trovali nella 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 Default Workspace. 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 stampano 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 nei report dell'API Usage and Cost e sugli oggetti dell'Admin API come le chiavi API (entrambi riportano null per il Default Workspace, come fanno anche le chiavi API per le chiavi di tutti i workspace; il campo scope di una chiave API distingue i due e, per una chiave associata a un workspace, riporta l'ID reale di quel workspace)
• Verificare se si tratta dell'ID del tuo Default Workspace passandolo a Get Workspace con una chiave Admin API: il Default Workspace viene restituito con "name": "Default", anche se List Workspaces 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 Workspaces (platform.claude.com/settings/workspaces) nella Claude Console e seleziona il workspace. Nel pannello che si apre, fai clic su Spend limits.
• Limiti di velocità: Limita le richieste al minuto, i token di input al minuto o i token di output al minuto. Per impostarli, vai alla pagina Rate limits nella Claude Console, seleziona il workspace dal menu a discesa Workspace e fai clic su Edit accanto a un modello.

Per informazioni dettagliate sui limiti di velocità e su come funzionano, consulta Limiti di velocità. Puoi anche leggere i limiti di velocità correnti della tua organizzazione e del workspace in modo programmatico con l'API Rate Limits.

Tracciamento dell'utilizzo e dei costi

Traccia l'utilizzo e i costi per workspace utilizzando l'API Usage and Cost:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
group_by[]=workspace_id&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

L'utilizzo e i costi attribuiti al Default Workspace hanno un valore null per workspace_id.

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 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