Admin API

L'Admin API ti consente di gestire in modo programmatico i membri, i workspace, gli inviti e le chiavi API della tua organizzazione, invece di farlo manualmente nella Claude Console.

Autenticazione

Autenticati con una qualsiasi delle tre credenziali. Una chiave Admin API copre la maggior parte degli endpoint. Gli endpoint relativi ad account di servizio, issuer di federazione e regole di federazione accettano solo un token OAuth org:admin. Invia una chiave personale o una chiave di account di servizio nell'header x-api-key, come faresti con una chiave Admin API. Gli esempi seguenti chiamano l'endpoint delle informazioni sull'organizzazione con un token OAuth e con una chiave Admin API.

Gli SDK Python, TypeScript, C#, Go, Java, PHP e Ruby espongono l'Admin API sotto client.beta.organization, e la CLI ant sotto ant beta:organization. Gli esempi in questa pagina usano il client predefinito, che legge una chiave Admin API da ANTHROPIC_API_KEY oppure un token bearer OAuth da ANTHROPIC_AUTH_TOKEN. I metodi di elenco degli SDK in Python, TypeScript, C#, Go e Java restituiscono un iteratore che recupera ulteriori pagine su richiesta, quindi limit imposta la dimensione della pagina, non il totale. Gli esempi PHP, Ruby e curl restituiscono una sola pagina. Nella CLI, --limit limita i risultati negli elenchi di membri, inviti, workspace, membri dei workspace e chiavi API. Per i parametri e le risposte di ciascun endpoint, consulta il riferimento dell'Admin API.

Token bearer OAuth

Accedi con la CLI ant usando un profilo dedicato con lo scope org:admin (consulta Accesso admin), quindi esporta il token bearer. --profile admin memorizza la credenziale org:admin in un profilo separato e lo rende il profilo attivo della CLI. La variabile esportata si applica a ogni chiamata SDK e CLI in quella shell. Usa una shell riservata all'amministrazione, rimuovi la variabile quando hai finito e riporta la CLI al profilo precedente con ant profile activate default:

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_AUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)

I token interattivi hanno breve durata. Se le richieste iniziano a restituire 401, esegui nuovamente il comando export per aggiornare il token.

Gli SDK e la CLI ant leggono ANTHROPIC_AUTH_TOKEN automaticamente. Lascia ANTHROPIC_API_KEY non impostata nella stessa shell in modo che inviino il token bearer. I carichi di lavoro automatizzati saltano il login: si autenticano tramite workload identity federation, e gli SDK e la CLI eseguono lo scambio di token a partire dalle variabili d'ambiente di federazione. Consulta Avviare un carico di lavoro per gestire WIF.

Chiama l'Admin API con il token esportato:

client = anthropic.Anthropic()

organization = client.beta.organization.retrieve()

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

Un token org:admin concede l'accesso all'intera organizzazione, indipendentemente dal workspace a cui è associato il profilo sottostante o la regola di federazione.

Per CI e altri carichi di lavoro non interattivi, genera il token con Workload Identity Federation invece di accedere in modo interattivo. Consulta Gestire WIF con l'Admin API.

Chiave Admin API

Per creare una chiave Admin API per il tuo tipo di organizzazione, consulta Creare una chiave Admin API.

client = anthropic.Anthropic()

organization = client.beta.organization.retrieve()

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

Come funziona l'Admin API

Autenticati con una qualsiasi credenziale descritta in Autenticazione, quindi gestisci le seguenti risorse:

• Membri dell'organizzazione e relativi ruoli
• Inviti all'organizzazione
• Workspace e relativi membri
• Chiavi API
• Account di servizio, issuer di federazione e regole di federazione (solo token OAuth org:admin)

Gli usi comuni includono l'automazione di onboarding e offboarding, la gestione dell'accesso ai workspace e l'audit delle chiavi API.

Ruoli e autorizzazioni dell'organizzazione

Esistono cinque ruoli a livello di organizzazione. Per i dettagli, consulta Ruoli e autorizzazioni della API Console.

Gli owner e i primary owner dell'organizzazione hanno tutte le autorizzazioni admin e possono anche gestire gli admin. Tutti i riferimenti al ruolo admin in questa pagina si applicano anche agli owner e ai primary owner.

Concetti chiave

Membri dell'organizzazione

Elenca i membri dell'organizzazione, aggiorna i loro ruoli e rimuovili.

Elenca i membri della tua organizzazione:

client = anthropic.Anthropic()

users = client.beta.organization.users.list(limit=10)

# Recupera automaticamente altre pagine secondo necessità.
for user in users:
    print(f"{user.id}: {user.email} ({user.role})")

Aggiorna il ruolo di un membro:

client = anthropic.Anthropic()

user = client.beta.organization.users.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6", role="developer"
)

print(f"id: {user.id}")
print(f"role: {user.role}")

Rimuovi un membro dall'organizzazione:

client = anthropic.Anthropic()

removed_user = client.beta.organization.users.remove("user_01XyDMpzjS89pFZXqSFUBDr6")

print(f"id: {removed_user.id}")

Inviti all'organizzazione

Invita utenti nella tua organizzazione e gestisci gli inviti in sospeso.

Invita un utente nella tua organizzazione:

client = anthropic.Anthropic()

invite = client.beta.organization.invites.create(
    email="user@example.com", role="developer"
)

print(f"id: {invite.id}")
print(f"email: {invite.email}")
print(f"status: {invite.status}")
print(f"expires_at: {invite.expires_at}")

Elenca gli inviti in sospeso:

client = anthropic.Anthropic()

invites = client.beta.organization.invites.list(limit=10)

# Recupera automaticamente altre pagine secondo necessità.
for invite in invites:
    print(f"{invite.id}: {invite.email} ({invite.status})")

Elimina un invito:

client = anthropic.Anthropic()

deleted_invite = client.beta.organization.invites.delete(
    "invite_015gWxHNr6h6TdRPZTmuCGnn"
)

print(f"id: {deleted_invite.id}")

Workspace

Consulta Workspace per esempi relativi alla Console e all'API.

Membri dei workspace

Gestisci l'accesso degli utenti a workspace specifici:

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}")

Elenca i membri di un workspace:

client = anthropic.Anthropic()

members = client.beta.organization.workspaces.members.list(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", limit=10
)

# Recupera automaticamente altre pagine secondo necessità.
for member in members:
    print(f"{member.user_id}: {member.workspace_role}")

Aggiorna il ruolo di un membro del workspace:

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}")

Chiavi API

Monitora e gestisci le chiavi API. Ogni chiave nella risposta include il proprio timestamp expires_at (null per le chiavi senza scadenza) e principal, l'identità per conto della quale agisce (consulta Tipi di chiave). Per una chiave personale, principal è {"type": "user_actor", "user_id": "user_..."}; per una chiave di account di servizio, {"type": "service_account_actor", "service_account_id": "svac_..."}; e per una chiave di workspace, null. Ogni chiave ha anche un oggetto scope: {"type": "workspace", "workspace_id": "wrkspc_..."} per una chiave associata a un singolo workspace, oppure {"type": "organization"} per una chiave che può operare su qualsiasi workspace a cui l'account ha accesso. Il campo di primo livello workspace_id è deprecato ed è null sia per le chiavi associate al Default Workspace sia per le chiavi senza scope di workspace; usa scope per distinguerle. Filtrando l'elenco per workspace_id con l'ID del Default Workspace vengono restituite solo le chiavi associate al Default Workspace; le chiavi senza scope di workspace non vengono restituite con alcun filtro workspace_id.

Elenca le chiavi API attive in un workspace:

client = anthropic.Anthropic()

api_keys = client.beta.organization.api_keys.list(
    limit=10, status="active", workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
)

# Recupera automaticamente altre pagine secondo necessità.
for api_key in api_keys:
    print(f"{api_key.id}: {api_key.name} ({api_key.status})")

Rinomina o disattiva una chiave API:

client = anthropic.Anthropic()

api_key = client.beta.organization.api_keys.update(
    "apikey_01Rj2N8SVvo6BePZj99NhmiT", status="inactive", name="New Key Name"
)

print(f"id: {api_key.id}")
print(f"name: {api_key.name}")
print(f"status: {api_key.status}")

Account di servizio

Crea e gestisci gli account di servizio (svac_...), le identità non umane per conto delle quali agiscono le chiavi di account di servizio e i token di Workload Identity Federation. Questi endpoint, come quelli degli issuer di federazione e delle regole di federazione, richiedono un token OAuth org:admin. Consulta Gestire WIF con l'Admin API.

Issuer di federazione

Registra gli identity provider OIDC (fdis_...) i cui token possono attestare l'identità dei carichi di lavoro per la tua organizzazione. Consulta Gestire WIF con l'Admin API.

Regole di federazione

Gestisci le regole (fdrl_...) che mappano i token degli issuer ad account di servizio e scope. Consulta Gestire WIF con l'Admin API.

Accesso alle informazioni sull'organizzazione

L'endpoint /v1/organizations/me restituisce l'organizzazione a cui appartiene la tua credenziale:

client = anthropic.Anthropic()

organization = client.beta.organization.retrieve()

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

{
  "id": "12345678-1234-5678-1234-567812345678",
  "type": "organization",
  "name": "Organization Name"
}

Per i dettagli sui parametri e gli schemi di risposta, consulta il riferimento dell'API Organization Info.

Report su utilizzo e costi

Monitora l'utilizzo e i costi della tua organizzazione con l'API Usage and Cost.

Analisi di Claude Code

Monitora la produttività degli sviluppatori e l'adozione di Claude Code con la Claude Code Analytics API.

Limiti di velocità

Leggi i "rate limit" (limiti di velocità) configurati per la tua organizzazione e i suoi workspace con la Rate Limits API.

Compliance API

Recupera i dati di audit e di attività della tua organizzazione con la Compliance API. Le chiavi Admin API possono leggere solo l'Activity Feed. Per l'accesso completo, consulta Configurare la Compliance API.

Best practice

• Usa nomi e descrizioni significativi per workspace e chiavi API
• Gestisci gli errori delle operazioni non riuscite
• Verifica regolarmente i ruoli e le autorizzazioni dei membri
• Elimina i workspace inutilizzati e gli inviti scaduti
• Monitora l'utilizzo delle chiavi API, verifica l'expires_at di ciascuna chiave e ruota le chiavi periodicamente

FAQ

Per domande specifiche sui workspace, consulta le FAQ sui workspace.