WIF mit der Admin API verwalten

Mit der Admin API kannst du Workload Identity Federation-Ressourcen programmatisch erstellen und verwalten: Service-Accounts, Federation-Issuer und Federation-Regeln. Nutze 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. Dieser 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 Möglichkeiten, ein Token zu erhalten, und sie bringen unterschiedliche Berechtigungen mit sich: 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), dann exportiere 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 anfangen, 401 zurückzugeben, führe den Export-Befehl erneut aus (er aktualisiert das Token automatisch).

Workload (CI und Automatisierung): Erstelle eine Federation-Regel mit oauth_scope: org:admin, die auf einen Service-Account abzielt, dessen organization_role auf admin gesetzt 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 sich Automatisierung selbst bootstrappen kann. Der nächste Abschnitt führt dich durch diese einmalige Einrichtung pro Organisation.



Einen Workload zum Verwalten 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-Regel über diese API verwalten.

Welche Operationen ein vom 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Admin-API-Keys werden an diesen Endpunkten nicht akzeptiert; die x-api-key-Beispiele auf 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "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" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Archiviere ein Service-Konto
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"

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 Workspaces sein, bevor föderierte Tokens darin agieren können. Jeder Service-Account hat eine implizite Mitgliedschaft im Default-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 Response-Schemas 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 Signing-Keys des Providers abruft:

# Registriere einen Issuer (GitHub Actions, mit JWKS-Discovery)
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"}
  }'

# Liste Issuer auf
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"

# Archiviere einen 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"

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 eine Regel stützt, deren oauth_scope etwas anderes als workspace:developer oder workspace:inference ist; siehe Berechtigungen und Einschränkungen.

Vollständige Parameterdetails und Response-Schemas findest du in der Federation-Issuer-API-Referenz.



Federation-Regeln

Eine Federation-Regel (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 das 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. Entweder workspace_id oder applies_to_all_workspaces: true ist beim Erstellen erforderlich.

# Erstelle eine Regel (GitHub Actions deployt vom main-Branch)
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
  }'

# Liste Regeln auf, optional gefiltert nach Aussteller
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"

# Archiviere eine Regel
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"

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 Tokens ausstellen 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 Response-Schemas findest du in der Federation-Regeln-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-Regeln 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 bei der nächsten Anfrage. Die Liste der Rule-Workspaces-Sub-Ressource gibt die vollständige Menge ohne Paginierung zurück. Archivierte Ressourcen sind standardmäßig aus 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-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 Organisationsverwaltungs-Oberfläche
• Admin-API-Referenz: generierte Request- und Response-Schemas für jeden Admin-API-Endpunkt