Workspace

I workspace (spazi di lavoro) 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 team account 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 non compare nei risultati di List Workspaces, 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 legata 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 con l'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 vi aggiunge quel membro. 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 manualmente al suo interno 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 di workspace.
• L'utilizzo di Claude Code è soggetto a limiti di velocità separati, e gli amministratori possono limitare la sua quota dei limiti dell'organizzazione in Settings > Workspaces.
• È 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 gli sviluppatori dell'organizzazione devono essere aggiunti esplicitamente a ciascun workspace
• Gli account di servizio vengono aggiunti ai workspace dalla pagina dell'account di servizio in Settings → Service accounts o dalla scheda Service accounts del workspace

Gestione dei workspace

Usando la Console

Crea e gestisci i workspace nella Claude Console.

Crea un workspace

1. 1

   Apri le impostazioni dei workspace

   Nella Claude Console, vai a Settings > Workspaces.

2. 2

   Crea un workspace

   Fai clic su Create workspace.

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 per finalizzare.

Modifica i dettagli del workspace

Per modificare il nome o il colore di un workspace:

1. Seleziona il workspace dall'elenco.
2. Fai clic sul menu con i puntini di sospensione (...) e scegli Edit details.
3. Aggiorna il nome o il colore e salva le modifiche.

Aggiungi membri a un workspace

1. Vai alla scheda Members del workspace.
2. Fai clic su Add to Workspace.
3. Seleziona un membro dell'organizzazione e assegnagli un ruolo del workspace.
4. Conferma l'aggiunta.

Per rimuovere un membro, fai clic sull'icona del cestino accanto al suo nome.

Imposta i limiti del workspace

Le impostazioni di ciascun workspace li suddividono in due schede:

• Limiti di velocità: nella scheda Rate limits, imposta limiti per livello di modello per richieste al minuto, token di input o token di output
• Limiti di spesa: nella scheda Spend limits, limita la spesa mensile e configura avvisi quando la spesa raggiunge determinate soglie

Archivia un workspace

Per archiviare un workspace, fai clic sul menu con i puntini di sospensione (...) e seleziona Archive. L'archiviazione:

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

Usando l'Admin API

Gestisci i workspace in modo programmatico usando 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.beta.organization.workspaces. I metodi list degli 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.beta.organization.workspaces.create(name="Production")

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

Elenca i workspace:

client = anthropic.Anthropic()

workspaces = client.beta.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.beta.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 API Workspaces.

Gestione dei membri del workspace

Aggiungi un membro a un workspace:

client = anthropic.Anthropic()

member = client.beta.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.beta.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.beta.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 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 di 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 workspace singolo viene sempre eseguita nel workspace scelto al momento della 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 usare.

Le risorse con ambito limitato ai workspace includono:

• File creati tramite la Files API
• Message Batches creati tramite la Batch API
• Skills create tramite la Skills API

Alcune risorse sono gestite in modo diverso:

• I tunnel MCP sono gestiti con un token OAuth workspace:manage_tunnels ottenuto tramite Workload Identity Federation, non con una chiave API. I tunnel vengono creati in un workspace, e l'elenco MCP tunnels della Console e il selettore di server di Managed Agent mostrano solo i tunnel del 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 sono gestiti a livello di organizzazione tramite l'Admin API, usando una chiave Admin API, un token OAuth org:admin, oppure una chiave personale o di account di servizio che non sia limitata a un workspace specifico.

Per cercare gli ID dei workspace della tua organizzazione, chiama l'endpoint List Workspaces oppure trovali nella Claude Console.

Identifica il workspace dietro una risposta API

Le risposte della Claude API 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 è stata risolta la chiave API o il token di accesso della richiesta, anche 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 all'Admin API) o quando la richiesta fallisce prima del completamento dell'autenticazione, come nel caso di un errore 401.

I seguenti esempi inviano una richiesta alla Messages API e stampano l'ID del workspace dagli header di risposta:

client = anthropic.Anthropic()

response = client.messages.with_raw_response.create(
    model="claude-opus-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 della Claude API, incluse le API di 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 ottenuto da una risposta, puoi:

• Confermare verso l'utilizzo, i costi e i limiti di velocità di quale workspace è stata conteggiata la richiesta
• Confrontarlo con il campo workspace_id nei report della Usage and Cost API 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 valide per tutti i workspace; il campo scope di una chiave API distingue i due casi e, per una chiave legata a un solo workspace, contiene l'ID reale di quel workspace)
• Verificare se è l'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
• Aprire quel workspace nella Console per trovare le risorse della richiesta, come sessioni, file, message batches e skills

Limiti dei workspace

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

Impostazione dei limiti dei workspace

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

• Limiti di spesa: limita la spesa mensile per un workspace. Impostali nella scheda delle impostazioni Spend limits del workspace nella Claude Console.
• Limiti di velocità: limita le richieste al minuto, i token di input al minuto o i token di output al minuto. Impostali nella scheda delle impostazioni Rate limits del workspace nella Claude Console.

Per informazioni dettagliate sui limiti di velocità e sul loro funzionamento, consulta Limiti di velocità. Puoi anche leggere in modo programmatico i limiti di velocità correnti della tua organizzazione e dei tuoi workspace con la Rate Limits API.

Monitoraggio di utilizzo e costi

Monitora utilizzo e costi per workspace usando la Usage and Cost API:

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 per team o reparto

Assegna 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 rivolti ai clienti

Organizzazione basata su progetti

Crea workspace per progetti o prodotti specifici per monitorare utilizzo e costi separatamente.

Best practice

1. 1

   Pianifica la struttura dei tuoi workspace

   Valuta come organizzerai i workspace prima di crearli. Pensa alle esigenze di fatturazione, controllo degli accessi e monitoraggio dell'utilizzo.

2. 2

   Usa nomi significativi

   Assegna ai workspace nomi chiari che ne indichino lo scopo (ad esempio, "Production - Customer Chatbot" o "Dev - Internal Tools").

3. 3

   Imposta limiti appropriati

   Configura 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 la Usage and Cost API per monitorare il consumo a livello di workspace.

FAQ

Vedi anche

• Admin API
• Riferimento Admin API
• Limiti di velocità
• Usage and Cost API