Gestisci WIF con l'Admin API

L'Admin API ti consente di creare e gestire in modo programmatico le risorse di Workload Identity Federation: service account, federation issuer e federation rule. Usala per mantenere la configurazione della federazione come "infrastructure as code" (infrastruttura come codice), effettuarne il provisioning dalla CI e riprodurla tra organizzazioni invece di fare clic attraverso la Claude Console. Questi endpoint condividono il prefisso di percorso /v1/organizations con il resto dell'Admin API.

Prerequisiti

Ogni richiesta in questa pagina si autentica con un bearer token OAuth che porta lo scope org:admin. Lo scope viene concesso solo ai membri dell'organizzazione con il ruolo admin, owner o primary owner, e concede l'accesso all'intera organizzazione: qualsiasi associazione a un workspace viene ignorata. Esistono due modi per ottenere un token, e comportano permessi diversi: un token ottenuto dal tuo login agisce come utente, mentre un token federato agisce come service account e non può eseguire tutte le operazioni descritte in questa pagina.

Interattivo (il tuo terminale)

Accedi con la CLI ant sotto un profilo dedicato, richiedendo lo scope org:admin (vedi Accesso admin), quindi esporta il bearer token. L'accesso con --profile admin memorizza la credenziale org:admin sotto il proprio nome di profilo e la rende anche il profilo attivo della CLI, e la variabile esportata si applica a ogni chiamata SDK e CLI in quella shell; usa quindi 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 di export (aggiorna il token automaticamente).

Gli SDK e la CLI ant leggono ANTHROPIC_AUTH_TOKEN automaticamente; lascia ANTHROPIC_API_KEY non impostata nella stessa shell, perché questi endpoint rifiutano le chiavi API e alcuni client preferiscono la chiave quando entrambe sono impostate.

Workload (CI e automazione)

Crea una federation rule con oauth_scope: org:admin che abbia come target un service account il cui organization_role sia admin. La regola stessa deve essere creata nella Claude Console: concedere a un workload l'accesso come admin dell'organizzazione è un'azione umana deliberata, non qualcosa che l'automazione può avviare da sola. La sezione successiva illustra questa configurazione da eseguire una sola volta per organizzazione.

Avvia un workload per gestire WIF

Una sola regola creata nella Console è sufficiente per mettere il resto della configurazione della federazione sotto infrastructure as code: concedi a un singolo workload fidato lo scope org:admin e lascia che quel workload gestisca i federation issuer e ogni federation rule con scope di workspace tramite questa API.

1. 1

   Crea la regola org:admin nella Console

   Nella Claude Console, vai su Settings → Workload identity e seleziona Connect workload per creare una federation rule per il tuo workload di automazione, ad esempio un workflow GitHub Actions nel tuo repository di infrastruttura. In Advanced rule options, imposta lo scope OAuth della regola su org:admin: la procedura guidata crea quindi il nuovo service account con il ruolo di organizzazione Admin (oppure ti chiede di scegliere un service account admin esistente come target).

2. 2

   Scambia il token di identità del workload

   Un workload che usa uno degli SDK o la CLI ant non esegue lo scambio da solo. Indirizza il client alla regola con le variabili d'ambiente della federazione e costruiscilo senza argomenti, esattamente come per l'inferenza in Costruisci il client SDK; il client scambia il token di identità alla prima richiesta e, prima che l'access token risultante scada, rilegge il token di identità e lo scambia di nuovo:

   export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...        # the org:admin rule from step 1
   export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
   export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...       # the rule's target service account
   export ANTHROPIC_IDENTITY_TOKEN_FILE=/path/to/jwt  # or ANTHROPIC_IDENTITY_TOKEN
   # ANTHROPIC_WORKSPACE_ID è richiesto solo se la regola è abilitata per tutti
   # i workspace o per più di uno; gli endpoint org:admin ignorano l'associazione.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   La CLI ant legge le stesse variabili, oppure accetta i flag --federation-rule, --organization-id, --service-account-id e --identity-token-file. Per un workload che esegue più di un comando ant, usa un profilo di federazione invece di flag o variabili d'ambiente: con flag o variabili la CLI scambia nuovamente il token di identità in ogni processo, e i token di identità che portano un claim jti (i token di GitHub Actions lo fanno) vengono accettati una sola volta, quindi un secondo comando verrebbe rifiutato; un profilo è anche l'unico modo per fornire alla CLI un workspace_id per lo scambio quando la regola è abilitata per tutti i workspace o per più di uno, perché a differenza degli SDK la CLI non passa ANTHROPIC_WORKSPACE_ID o --workspace-id nello scambio. Ogni SDK accetta inoltre le stesse impostazioni come argomenti espliciti del costruttore, mostrati per ciascun linguaggio in Costruisci il client SDK. Vedi Variabili d'ambiente e Precedenza delle credenziali per l'elenco completo e l'ordinamento.

   Un workload che chiama l'API con curl scambia da solo il JWT con un bearer token org:admin di breve durata, usando lo stesso scambio di token di qualsiasi altro workload federato, e lo invia nell'header authorization: Bearer.

3. 3

   Gestisci issuer e regole con scope di workspace tramite l'API

   Con il client configurato (oppure, per curl, con il token emesso in ANTHROPIC_AUTH_TOKEN), il workload crea e gestisce la configurazione della federazione usando gli endpoint di questa pagina.

Per le operazioni che un token emesso da un workload può e non può eseguire, vedi Permessi e vincoli. Se hai già creato issuer, service account o regole con la procedura guidata Connect workload, elencali con gli endpoint seguenti e importali nello stato della tua infrastructure-as-code invece di ricrearli.

Autenticazione

Tutti gli endpoint si trovano sotto https://api.anthropic.com/v1/organizations/. Ogni richiesta agli endpoint di federazione e dei service account richiede l'header della versione API e il bearer token:

Negli SDK questi endpoint sono client.beta.organization.service_accounts, client.beta.organization.federation.issuers e client.beta.organization.federation.rules (ant beta:organization:service-accounts, federation:issuers e federation:rules nella CLI). Gli esempi SDK e CLI costruiscono il client predefinito, che invia il bearer token da ANTHROPIC_AUTH_TOKEN oppure, in un workload automatizzato, esegue da solo lo scambio di federazione come descritto in Avvia un workload per gestire WIF. I metodi list degli SDK recuperano le pagine successive su richiesta, quindi limit imposta la dimensione della pagina; gli esempi PHP e Ruby leggono una sola pagina.

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list()

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Le chiavi Admin API non sono accettate su questi endpoint; gli esempi x-api-key della pagina dell'Admin API non si applicano qui.

Service account

Un service account (svac_...) è l'identità non umana come cui agisce un token federato. Imposta organization_role su developer.

Crea un service account:

client = anthropic.Anthropic()

service_account = client.beta.organization.service_accounts.create(
    name="inference-worker", organization_role="developer"
)

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

Elenca i service account:

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list(limit=20)

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Archivia un service account:

client = anthropic.Anthropic()

service_account = client.beta.organization.service_accounts.archive(
    "svac_01ABCDEFabcdef0123456789XY"
)

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

L'endpoint di creazione restituisce il nuovo service account:

{
  "id": "svac_...",
  "name": "inference-worker",
  "organization_role": "developer",
  "created_at": "...",
  "type": "service_account",
  "...": "..."
}

Per leggere o aggiornare un singolo service account, usa GET e POST su /v1/organizations/service_accounts/{service_account_id}. Un service account deve essere membro di un workspace prima che i token federati possano agire al suo interno. Ogni service account ha un'appartenenza implicita al workspace predefinito della tua organizzazione; aggiungi appartenenze esplicite per altri workspace con GET, POST e DELETE su /v1/organizations/service_accounts/{service_account_id}/workspaces, dove DELETE ha come target .../workspaces/{workspace_id}.

Per i dettagli completi dei parametri e gli schemi di risposta, vedi il riferimento API dei service account.

Federation issuer

Un federation issuer (fdis_...) registra un identity provider OIDC presso la tua organizzazione. Il campo jwks è una discriminated union che controlla il modo in cui Anthropic recupera le chiavi di firma del provider:

Registra un issuer. Questo esempio registra GitHub Actions con discovery JWKS:

client = anthropic.Anthropic()

issuer = client.beta.organization.federation.issuers.create(
    name="github-actions",
    issuer_url="https://token.actions.githubusercontent.com",
    jwks={"type": "discovery"},
)

print(f"id: {issuer.id}")
print(f"name: {issuer.name}")
print(f"issuer_url: {issuer.issuer_url}")

Elenca gli issuer:

client = anthropic.Anthropic()

issuers = client.beta.organization.federation.issuers.list(limit=20)

for issuer in issuers:
    print(f"{issuer.id}: {issuer.name}")

Archivia un issuer:

client = anthropic.Anthropic()

issuer = client.beta.organization.federation.issuers.archive(
    "fdis_01ABCDEFabcdef0123456789XY"
)

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

Per leggere o aggiornare un singolo issuer, usa GET e POST su /v1/organizations/federation_issuers/{issuer_id}. Un chiamante OAuth non può aggiornare un issuer che supporta una regola il cui oauth_scope sia diverso da workspace:developer o workspace:inference; vedi Permessi e vincoli.

Per i dettagli completi dei parametri e gli schemi di risposta, vedi il riferimento API dei federation issuer.

Federation rule

Una federation rule (fdrl_...) associa un issuer a un service account: i JWT dell'issuer che soddisfano le condizioni di corrispondenza della regola possono emettere token che agiscono come il target della regola. Il workspace_id nella richiesta di creazione abilita la regola in quel workspace al momento della creazione; aggiungi altri workspace in seguito tramite la sotto-risorsa /federation_rules/{rule_id}/workspaces. In fase di creazione è richiesto workspace_id oppure applies_to_all_workspaces: true.

Crea una regola. Questo esempio consente ai deploy di GitHub Actions dal branch main di agire come il service account:

client = anthropic.Anthropic()

rule = client.beta.organization.federation.rules.create(
    name="gha-deploy",
    issuer_id="fdis_01ABCDEFabcdef0123456789XY",
    match={
        "subject_prefix": "repo:my-org/my-repo:ref:refs/heads/main",
        "claims": {"repository_owner": "my-org"},
    },
    target={
        "type": "service_account",
        "service_account_id": "svac_01ABCDEFabcdef0123456789XY",
    },
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    oauth_scope="workspace:developer",
    token_lifetime_seconds=600,
)

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

Elenca le regole, facoltativamente filtrate per issuer:

client = anthropic.Anthropic()

rules = client.beta.organization.federation.rules.list(
    issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)

for rule in rules:
    print(f"{rule.id}: {rule.name}")

Archivia una regola:

client = anthropic.Anthropic()

rule = client.beta.organization.federation.rules.archive(
    "fdrl_01ABCDEFabcdef0123456789XY"
)

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

L'endpoint di elenco restituisce una pagina di regole e il cursore per la pagina successiva:

{
  "data": [{ "id": "fdrl_...", "name": "gha-deploy", "...": "..." }],
  "next_page": "..."
}

Per leggere o aggiornare una singola regola, usa GET e POST su /v1/organizations/federation_rules/{rule_id}. Per gestire i workspace in cui una regola può emettere token, usa GET e POST su /v1/organizations/federation_rules/{rule_id}/workspaces, e DELETE su /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Per i dettagli completi dei parametri e gli schemi di risposta, vedi il riferimento API delle federation rule.

Permessi e vincoli

Una regola con oauth_scope: org:admin deve avere come target un service account il cui organization_role sia admin. I nomi delle risorse devono corrispondere a ^[a-z0-9-]+$, avere da 1 a 255 caratteri ed essere univoci all'interno di un'organizzazione per ciascun tipo di risorsa; per i vincoli completi a livello di campo, vedi Regole di validazione.

Paginazione e archiviazione

Gli endpoint di elenco dei service account, dei federation issuer e delle federation rule accettano limit (da 1 a 100, predefinito 20) e un cursore page preso dalla risposta precedente. Passa il valore next_page della risposta come parametro di query page nella richiesta successiva. L'elenco della sotto-risorsa dei workspace di una regola restituisce l'insieme completo senza paginazione. Le risorse archiviate sono nascoste dagli elenchi per impostazione predefinita; passa include_archived=true per includerle.

L'archiviazione è un soft delete ed è idempotente: archiviare una risorsa già archiviata ha esito positivo. L'archiviazione di un issuer o di un service account restituisce 400 finché una federation rule attiva vi fa ancora riferimento; archivia prima la regola.

Vedi anche

• Workload Identity Federation: concetti e procedura guidata di configurazione nella Console
• Riferimento WIF: variabili d'ambiente, regole di validazione, scope OAuth e codici di errore
• Admin API: il resto della superficie di gestione dell'organizzazione
• Riferimento Admin API: schemi di richiesta e risposta generati per ogni endpoint dell'Admin API