Gestire WIF con l'Admin API

L'Admin API ti consente di creare e gestire le risorse di Workload Identity Federation in modo programmatico: service account, federation issuer e federation rule. Usala per mantenere la tua configurazione di federazione come infrastructure as code, effettuarne il provisioning dalla CI e riprodurla tra diverse organizzazioni invece di navigare manualmente nella 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 token bearer OAuth che include lo scope org:admin. Lo scope viene concesso solo ai membri dell'organizzazione con il ruolo di admin, owner o primary owner, e garantisce 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 (dal tuo terminale): Accedi con la CLI ant usando un profilo dedicato, richiedendo lo scope org:admin (vedi Accesso admin), quindi esporta il token bearer:

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

I token interattivi hanno vita breve; se le richieste iniziano a restituire 401, esegui nuovamente il comando di export (aggiorna automaticamente il token).

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 di amministratore 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.



Bootstrap di un workload per gestire WIF

Una sola regola creata dalla Console è sufficiente per mettere il resto della tua configurazione di 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 tutte le federation rule con scope di workspace tramite questa API.

Per le operazioni che un token generato 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 del tuo 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 service account richiede l'header della versione API e il token bearer:

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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



Service account

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

# Crea un account di servizio
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# Elenca gli account di servizio
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Archivia un account di servizio
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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



Federation issuer

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

# Registra un issuer (GitHub Actions, con discovery JWKS)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "github-actions",
    "issuer_url": "https://token.actions.githubusercontent.com",
    "jwks": {"type": "discovery"}
  }'

# Elenca gli issuer
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Archivia un issuer
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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 è diverso da workspace:developer o workspace:inference; vedi Permessi e vincoli.



Federation rule

Una federation rule (fdrl_...) associa un issuer a un service account: i JWT provenienti dall'issuer che soddisfano le condizioni di corrispondenza della regola possono generare 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. Alla creazione è obbligatorio specificare workspace_id oppure applies_to_all_workspaces: true.

# Crea una regola (GitHub Actions esegue il deploy dal branch main)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "gha-deploy",
    "issuer_id": "fdis_...",
    "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_..."
    },
    "workspace_id": "wrkspc_...",
    "oauth_scope": "workspace:developer",
    "token_lifetime_seconds": 600
  }'

# Elenca le regole, opzionalmente filtrate per emittente
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules?issuer_id=fdis_..." \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Archivia una regola
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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ò generare 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}.



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 una lunghezza compresa tra 1 e 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 per service account, federation issuer e 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 rule-workspaces restituisce l'intero set senza paginazione. Le risorse archiviate sono nascoste dagli elenchi per impostazione predefinita; passa include_archived=true per includerle.

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



Vedi anche

• Workload Identity Federation: concetti e guida alla configurazione tramite 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