WIF mit der Admin API verwalten

Die Admin API ermöglicht es dir, Workload Identity Federation-Ressourcen programmatisch zu erstellen und zu verwalten: Service Accounts, Federation Issuer und Federation Rules. Verwende sie, um deine Federation-Konfiguration als Infrastructure as Code zu pflegen, sie aus 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 er gewährt Zugriff auf die gesamte Organisation: jegliche Workspace-Bindung wird ignoriert. Es gibt zwei Möglichkeiten, ein Token zu erhalten, und sie tragen unterschiedliche Berechtigungen: Ein Token aus deinem eigenen Login agiert als Benutzer, während ein föderiertes Token als Service Account agiert und nicht jede Operation auf dieser Seite ausführen kann.



Interaktiv (dein Terminal)

Melde dich mit der ant CLI unter einem dedizierten Profil an und fordere dabei den Scope org:admin an (siehe Admin-Zugriff), exportiere dann das Bearer-Token:

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

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



Workload (CI und Automatisierung)

Erstelle eine Federation Rule mit oauth_scope: org:admin, die auf einen Service Account abzielt, 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, nichts, was 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 reicht aus, 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 Rule über diese API verwalten.

Welche Operationen ein von einem Workload ausgestelltes Token ausführen kann und welche nicht, findest du unter Berechtigungen und Einschränkungen. Wenn du bereits Issuer, Service Accounts oder Regeln mit dem Connect workload-Assistenten erstellt hast, liste sie mit den folgenden Endpunkten auf und importiere sie in deinen Infrastructure-as-Code-State, 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:

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

Admin-API-Keys werden auf 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 agiert. Setze organization_role auf developer.

# Erstelle ein Service-Konto
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# Liste Service-Konten auf
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts?limit=20" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Archiviere ein Service-Konto
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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 Tokens darin agieren 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} abzielt.

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



Federation Issuer

Ein Federation Issuer (fdis_...) registriert einen OIDC Identity Provider bei deiner Organisation. Das Feld jwks ist eine Discriminated Union, die steuert, wie Anthropic die Signaturschlüssel des Providers abruft:

# Registriere einen Issuer (GitHub Actions, mit JWKS-Discovery)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "name": "github-actions",
    "issuer_url": "https://token.actions.githubusercontent.com",
    "jwks": {"type": "discovery"}
  }'

# Liste Issuer auf
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers?limit=20" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Archiviere einen Issuer
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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 einer Regel zugrunde liegt, 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 Federation-Issuers-API-Referenz.



Federation Rules

Eine Federation Rule (fdrl_...) bindet einen Issuer an einen Service Account: JWTs vom Issuer, die die Match-Bedingungen der Regel erfüllen, können Tokens ausstellen, die als Ziel der Regel agieren. 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.

# Erstelle eine Regel (GitHub Actions deployt vom main-Branch)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "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
  }'

# Liste Regeln auf, optional gefiltert nach Aussteller
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules?issuer_id=fdis_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Archiviere eine Regel
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Der List-Endpunkt gibt eine Seite von 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 Tokens ausstellen kann, verwende GET und POST auf /v1/organizations/federation_rules/{rule_id}/workspaces und DELETE auf /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Vollständige Parameterdetails und Antwortschemata findest du in der Federation-Rules-API-Referenz.



Berechtigungen und Einschränkungen

Eine Regel mit oauth_scope: org:admin muss auf einen Service Account abzielen, 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 Rules akzeptieren limit (1 bis 100, Standard 20) und einen page-Cursor aus der vorherigen Antwort. Übergib den next_page-Wert der Antwort als page-Query-Parameter in der nächsten Anfrage. Die Liste der Rule-Workspaces-Sub-Ressource gibt den vollständigen Satz ohne Paginierung zurück. Archivierte Ressourcen werden standardmäßig in Listen ausgeblendet; übergib include_archived=true, um sie einzuschließen.

Archivierung 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 Rule 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 Organisationsverwaltungs-Oberfläche
• Admin-API-Referenz: generierte Anfrage- und Antwortschemata für jeden Admin-API-Endpunkt