WIF mit der Admin API verwalten

Mit der Admin API kannst du Ressourcen für Workload Identity Federation programmatisch erstellen und verwalten: Service-Accounts, Federation-Issuer und Federation-Regeln. Verwende sie, um deine Federation-Konfiguration als „infrastructure as code“ (Infrastruktur als Code) zu pflegen, sie aus der CI heraus bereitzustellen und sie über Organisationen hinweg zu reproduzieren, anstatt dich durch die Claude Console zu klicken. Diese Endpunkte teilen sich das Pfadpräfix /v1/organizations mit dem Rest der Admin API.

Voraussetzungen

Jede Anfrage auf dieser Seite authentifiziert sich mit einem OAuth-Bearer-Token, das den Scope org:admin trägt. Der Scope wird nur Organisationsmitgliedern mit der Rolle Admin, Owner oder Primary Owner gewährt und gewährt Zugriff auf die gesamte Organisation: Jede Workspace-Bindung wird ignoriert. Es gibt zwei Wege, ein Token zu erhalten, und sie tragen unterschiedliche Berechtigungen: Ein Token aus deinem eigenen Login handelt als Benutzer, während ein föderiertes Token als Service-Account handelt und nicht jede Operation auf dieser Seite ausführen kann.

Interaktiv (dein Terminal)

Melde dich mit der ant CLI unter einem dedizierten Profil an, fordere dabei den Scope org:admin an (siehe Admin-Zugriff) und exportiere dann das Bearer-Token. Die Anmeldung mit --profile admin speichert die org:admin-Anmeldedaten unter einem eigenen Profilnamen und macht dieses Profil außerdem zum aktiven Profil der CLI, und die exportierte Variable gilt für jeden SDK- und CLI-Aufruf in dieser Shell; verwende daher eine Shell, die du für die Administration reservierst, setze die Variable zurück, wenn du fertig bist, und schalte die CLI mit ant profile activate default zurück:

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

Interaktive Token sind kurzlebig; wenn Anfragen beginnen, 401 zurückzugeben, führe den Export-Befehl erneut aus (er aktualisiert das Token automatisch).

Die SDKs und die ant CLI lesen ANTHROPIC_AUTH_TOKEN automatisch; lass ANTHROPIC_API_KEY in derselben Shell ungesetzt, da diese Endpunkte API-Keys ablehnen und manche Clients den Key bevorzugen, wenn beide gesetzt sind.

Workload (CI und Automatisierung)

Erstelle eine Federation-Regel mit oauth_scope: org:admin, die auf einen Service-Account zielt, dessen organization_role admin ist. Die Regel selbst muss in der Claude Console erstellt werden: Einem Workload Organisations-Admin-Zugriff zu gewähren, ist eine bewusste menschliche Handlung und nichts, was eine Automatisierung für sich selbst bootstrappen kann. Der nächste Abschnitt führt durch diese einmalige Einrichtung pro Organisation.

Einen Workload zur Verwaltung von WIF bootstrappen

Eine einzige in der Console erstellte Regel genügt, um den Rest deiner Federation-Konfiguration unter Infrastructure as Code zu stellen: Gewähre einem einzelnen vertrauenswürdigen Workload den Scope org:admin und lass diesen Workload Federation-Issuer und jede Workspace-bezogene Federation-Regel über diese API verwalten.

1. 1

   Die org:admin-Regel in der Console erstellen

   Gehe in der Claude Console zu Settings → Workload identity und wähle Connect workload, um eine Federation-Regel für deinen Automatisierungs-Workload zu erstellen, zum Beispiel einen GitHub-Actions-Workflow in deinem Infrastruktur-Repository. Setze unter Advanced rule options den OAuth-Scope der Regel auf org:admin: Der Assistent erstellt dann den neuen Service-Account mit der Organisationsrolle Admin (oder fordert dich auf, einen bestehenden Admin-Service-Account als Ziel auszuwählen).

2. 2

   Das Identitätstoken des Workloads austauschen

   Ein Workload, der eines der SDKs oder die ant CLI verwendet, führt den Austausch nicht selbst durch. Richte den Client mit den Federation-Umgebungsvariablen auf die Regel aus und konstruiere ihn ohne Argumente, genau wie für Inferenz in Den SDK-Client konstruieren; der Client tauscht das Identitätstoken bei der ersten Anfrage aus und liest, bevor das resultierende Zugriffstoken abläuft, das Identitätstoken erneut ein und tauscht es wieder aus:

   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 ist nur erforderlich, wenn die Regel für alle
   # Workspaces oder mehr als einen aktiviert ist; die org:admin-Endpunkte ignorieren die Bindung.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   Die ant CLI liest dieselben Variablen oder akzeptiert die Flags --federation-rule, --organization-id, --service-account-id und --identity-token-file. Verwende für einen Workload, der mehr als einen ant-Befehl ausführt, ein Federation-Profil anstelle von Flags oder Umgebungsvariablen: Mit Flags oder Variablen tauscht die CLI das Identitätstoken in jedem Prozess erneut aus, und Identitätstoken, die einen jti-Claim tragen (GitHub-Actions-Token tun das), werden nur einmal akzeptiert, sodass ein zweiter Befehl abgelehnt würde; ein Profil ist außerdem der einzige Weg, der CLI eine workspace_id für den Austausch mitzugeben, wenn die Regel für alle Workspaces oder mehr als einen aktiviert ist, denn anders als die SDKs übergibt die CLI ANTHROPIC_WORKSPACE_ID oder --workspace-id nicht an den Austausch. Jedes SDK akzeptiert dieselben Einstellungen auch als explizite Konstruktorargumente, pro Sprache gezeigt in Den SDK-Client konstruieren. Siehe Umgebungsvariablen und Rangfolge der Anmeldedaten für die vollständige Liste und Reihenfolge.

   Ein Workload, der die API mit curl aufruft, tauscht das JWT selbst gegen ein kurzlebiges org:admin-Bearer-Token aus, mit demselben Token-Austausch wie jeder andere föderierte Workload, und sendet es im Header authorization: Bearer.

3. 3

   Issuer und Workspace-bezogene Regeln über die API verwalten

   Mit dem konfigurierten Client (oder, für curl, dem geprägten Token in ANTHROPIC_AUTH_TOKEN) erstellt und verwaltet der Workload deine Federation-Konfiguration mit den Endpunkten auf dieser Seite.

Welche Operationen ein vom Workload geprägtes Token ausführen kann und welche nicht, findest du unter Berechtigungen und Einschränkungen. Wenn du bereits Issuer, Service-Accounts oder Regeln mit dem Assistenten Connect workload erstellt hast, liste sie mit den folgenden Endpunkten auf und importiere sie in deinen Infrastructure-as-Code-Zustand, anstatt sie neu zu erstellen.

Authentifizierung

Alle Endpunkte liegen unter https://api.anthropic.com/v1/organizations/. Jede Anfrage an die Federation- und Service-Account-Endpunkte benötigt den API-Versions-Header und das Bearer-Token:

In den SDKs sind diese Endpunkte client.beta.organization.service_accounts, client.beta.organization.federation.issuers und client.beta.organization.federation.rules (ant beta:organization:service-accounts, federation:issuers und federation:rules in der CLI). Die SDK- und CLI-Beispiele konstruieren den Standard-Client, der das Bearer-Token aus ANTHROPIC_AUTH_TOKEN sendet oder, in einem automatisierten Workload, den Federation-Austausch selbst durchführt, wie in Einen Workload zur Verwaltung von WIF bootstrappen beschrieben. SDK-List-Methoden rufen weitere Seiten bei Bedarf ab, sodass limit die Seitengröße festlegt; die PHP- und Ruby-Beispiele lesen eine Seite.

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

Admin-API-Keys werden an diesen Endpunkten nicht akzeptiert; die x-api-key-Beispiele der Admin-API-Seite gelten hier nicht.

Service-Accounts

Ein Service-Account (svac_...) ist die nicht-menschliche Identität, als die ein föderiertes Token handelt. Setze organization_role auf developer.

Einen Service-Account erstellen:

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

Service-Accounts auflisten:

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

Einen Service-Account archivieren:

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

Der Create-Endpunkt gibt den neuen Service-Account zurück:

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

Um einen einzelnen Service-Account zu lesen oder zu aktualisieren, verwende GET und POST auf /v1/organizations/service_accounts/{service_account_id}. Ein Service-Account muss Mitglied eines Workspace sein, bevor föderierte Token darin handeln können. Jeder Service-Account hat eine implizite Mitgliedschaft im Standard-Workspace deiner Organisation; füge explizite Mitgliedschaften für andere Workspaces mit GET, POST und DELETE auf /v1/organizations/service_accounts/{service_account_id}/workspaces hinzu, wobei DELETE auf .../workspaces/{workspace_id} zielt.

Vollständige Parameterdetails und Antwortschemata findest du in der API-Referenz für Service-Accounts.

Federation-Issuer

Ein Federation-Issuer (fdis_...) registriert einen OIDC-Identitätsanbieter bei deiner Organisation. Das Feld jwks ist eine diskriminierte Union, die steuert, wie Anthropic die Signaturschlüssel des Anbieters abruft:

Einen Issuer registrieren. Dieses Beispiel registriert GitHub Actions mit JWKS-Discovery:

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

Issuer auflisten:

client = anthropic.Anthropic()

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

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

Einen Issuer archivieren:

client = anthropic.Anthropic()

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

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

Um einen einzelnen Issuer zu lesen oder zu aktualisieren, verwende GET und POST auf /v1/organizations/federation_issuers/{issuer_id}. Ein OAuth-Aufrufer kann keinen Issuer aktualisieren, der hinter einer Regel steht, deren oauth_scope etwas anderes als workspace:developer oder workspace:inference ist; siehe Berechtigungen und Einschränkungen.

Vollständige Parameterdetails und Antwortschemata findest du in der API-Referenz für Federation-Issuer.

Federation-Regeln

Eine Federation-Regel (fdrl_...) bindet einen Issuer an einen Service-Account: JWTs des Issuers, die die Match-Bedingungen der Regel erfüllen, können Token prägen, die als Ziel der Regel handeln. Die workspace_id in der Create-Anfrage aktiviert die Regel bei der Erstellung in diesem Workspace; füge später weitere Workspaces über die Sub-Ressource /federation_rules/{rule_id}/workspaces hinzu. Beim Erstellen ist entweder workspace_id oder applies_to_all_workspaces: true erforderlich.

Eine Regel erstellen. Dieses Beispiel lässt GitHub-Actions-Deployments vom main-Branch als der Service-Account handeln:

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

Regeln auflisten, optional nach Issuer gefiltert:

client = anthropic.Anthropic()

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

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

Eine Regel archivieren:

client = anthropic.Anthropic()

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

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

Der List-Endpunkt gibt eine Seite mit Regeln und den Cursor für die nächste Seite zurück:

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

Um eine einzelne Regel zu lesen oder zu aktualisieren, verwende GET und POST auf /v1/organizations/federation_rules/{rule_id}. Um die Workspaces zu verwalten, in denen eine Regel Token prägen kann, verwende GET und POST auf /v1/organizations/federation_rules/{rule_id}/workspaces sowie DELETE auf /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Vollständige Parameterdetails und Antwortschemata findest du in der API-Referenz für Federation-Regeln.

Berechtigungen und Einschränkungen

Eine Regel mit oauth_scope: org:admin muss auf einen Service-Account zielen, dessen organization_role admin ist. Ressourcennamen müssen ^[a-z0-9-]+$ entsprechen, 1 bis 255 Zeichen lang sein und innerhalb einer Organisation für jeden Ressourcentyp eindeutig sein; die vollständigen Einschränkungen auf Feldebene findest du unter Validierungsregeln.

Paginierung und Archivierung

Die List-Endpunkte für Service-Accounts, Federation-Issuer und Federation-Regeln akzeptieren limit (1 bis 100, Standard 20) und einen page-Cursor aus der vorherigen Antwort. Übergib den next_page-Wert der Antwort als Query-Parameter page bei der nächsten Anfrage. Die Liste der Sub-Ressource für Regel-Workspaces gibt die vollständige Menge ohne Paginierung zurück. Archivierte Ressourcen sind standardmäßig in Listen ausgeblendet; übergib include_archived=true, um sie einzuschließen.

Archivieren ist ein Soft-Delete und idempotent: Das Archivieren einer bereits archivierten Ressource ist erfolgreich. Das Archivieren eines Issuers oder eines Service-Accounts gibt 400 zurück, solange eine aktive Federation-Regel noch darauf verweist; archiviere zuerst die Regel.

Siehe auch

• Workload Identity Federation: Konzepte und die Schritt-für-Schritt-Einrichtung in der Console
• WIF-Referenz: Umgebungsvariablen, Validierungsregeln, OAuth-Scopes und Fehlercodes
• Admin API: der Rest der Oberfläche zur Organisationsverwaltung
• Admin-API-Referenz: generierte Anfrage- und Antwortschemata für jeden Admin-API-Endpunkt