AdminAuthentifizierung

WIF mit der Admin API verwalten

Erstelle und verwalte Service-Accounts, Issuer und Regeln für Workload Identity Federation programmatisch für Infrastructure-as-Code- und CI-Workflows.

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 Wege, 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:

CLI

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 zielt, 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 Automatisierung für sich selbst bootstrappen kann. Der nächste Abschnitt führt dich durch dieses einmalige Setup pro Organisation.

Einen Workload zum Verwalten von WIF bootstrappen

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

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).
Matche die Regel auf genau eine Workload-Identität, nicht auf ein breites Muster. subject_prefix ist ein exakter Match, es sei denn, er endet auf *. Für GitHub Actions pinne das Subject auf einen geschützten Branch, etwa repo:my-org/my-repo:ref:refs/heads/main. Eine abschließende Wildcard wie repo:my-org/my-repo:* matcht auch pull_request-Läufe, einschließlich Läufen, die von Forks ausgelöst werden – jeder, der einen Pull Request gegen das Repository öffnen könnte, könnte also ein org:admin-Token ausstellen. Siehe Einschränken, welche Workflows sich authentifizieren können.
Das Identity-Token des Workloads eintauschen
Zur Laufzeit tauscht der Workload das JWT von seinem Identity Provider gegen ein kurzlebiges org:admin-Bearer-Token ein – über denselben Token-Exchange wie jeder andere föderierte Workload.
Issuer und workspace-bezogene Regeln über die API verwalten
Mit dem ausgestellten Token in ANTHROPIC_OAUTH_TOKEN erstellt und verwaltet der Workload deine Federation-Konfiguration über die Endpunkte auf dieser Seite.

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

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.

cURL

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

Federation-Issuer

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

`jwks`-Wert	Wann verwenden
`{"type": "discovery"}`	Der Provider stellt `/.well-known/openid-configuration` unter der Issuer-URL bereit.
`{"type": "explicit_url", "url": "..."}`	Verweise direkt auf einen JWKS-Endpunkt.
`{"type": "inline", "keys": [...]}`	Lade das Key-Set hoch für Provider, die nicht aus dem öffentlichen Internet erreichbar sind.

cURL

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

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.

cURL

# 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 und DELETE auf /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Berechtigungen und Einschränkungen

OAuth-authentifizierte Aufrufer können nur Regeln erstellen oder ändern, deren oauth_scope workspace:developer oder workspace:inference ist. Um eine Regel mit einem anderen Scope (wie org:admin oder org:manage_tunnels) zu erstellen oder zu ändern, verwende die Console.
Ein OAuth-Aufrufer kann keinen Federation-Issuer aktualisieren, der eine Regel stützt, deren oauth_scope etwas anderes als workspace:developer oder workspace:inference ist (wie org:admin oder org:manage_tunnels). Erwäge, einen dedizierten Issuer für die Bootstrap-Regel zu registrieren, damit die Issuer hinter workspace-bezogenen Regeln über die API aktualisierbar bleiben.
Admin-API-Keys werden an diesen Endpunkten nicht akzeptiert, weder für Lese- noch für Schreibzugriffe; verwende ein org:admin-OAuth-Token.

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 page-Query-Parameter 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 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

Was this page helpful?

AdminAuthentifizierung

WIF mit der Admin API verwalten

Erstelle und verwalte Service-Accounts, Issuer und Regeln für Workload Identity Federation programmatisch für Infrastructure-as-Code- und CI-Workflows.

Voraussetzungen

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:

CLI

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

Einen Workload zum Verwalten von WIF bootstrappen

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).
Matche die Regel auf genau eine Workload-Identität, nicht auf ein breites Muster. subject_prefix ist ein exakter Match, es sei denn, er endet auf *. Für GitHub Actions pinne das Subject auf einen geschützten Branch, etwa repo:my-org/my-repo:ref:refs/heads/main. Eine abschließende Wildcard wie repo:my-org/my-repo:* matcht auch pull_request-Läufe, einschließlich Läufen, die von Forks ausgelöst werden – jeder, der einen Pull Request gegen das Repository öffnen könnte, könnte also ein org:admin-Token ausstellen. Siehe Einschränken, welche Workflows sich authentifizieren können.
Das Identity-Token des Workloads eintauschen
Zur Laufzeit tauscht der Workload das JWT von seinem Identity Provider gegen ein kurzlebiges org:admin-Bearer-Token ein – über denselben Token-Exchange wie jeder andere föderierte Workload.
Issuer und workspace-bezogene Regeln über die API verwalten
Mit dem ausgestellten Token in ANTHROPIC_OAUTH_TOKEN erstellt und verwaltet der Workload deine Federation-Konfiguration über die Endpunkte auf dieser Seite.

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

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.

cURL

# 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",
  "...": "..."
}

Federation-Issuer

`jwks`-Wert	Wann verwenden
`{"type": "discovery"}`	Der Provider stellt `/.well-known/openid-configuration` unter der Issuer-URL bereit.
`{"type": "explicit_url", "url": "..."}`	Verweise direkt auf einen JWKS-Endpunkt.
`{"type": "inline", "keys": [...]}`	Lade das Key-Set hoch für Provider, die nicht aus dem öffentlichen Internet erreichbar sind.

cURL

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

Federation-Regeln

cURL

# 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": "..."
}

Berechtigungen und Einschränkungen

OAuth-authentifizierte Aufrufer können nur Regeln erstellen oder ändern, deren oauth_scope workspace:developer oder workspace:inference ist. Um eine Regel mit einem anderen Scope (wie org:admin oder org:manage_tunnels) zu erstellen oder zu ändern, verwende die Console.
Ein OAuth-Aufrufer kann keinen Federation-Issuer aktualisieren, der eine Regel stützt, deren oauth_scope etwas anderes als workspace:developer oder workspace:inference ist (wie org:admin oder org:manage_tunnels). Erwäge, einen dedizierten Issuer für die Bootstrap-Regel zu registrieren, damit die Issuer hinter workspace-bezogenen Regeln über die API aktualisierbar bleiben.
Admin-API-Keys werden an diesen Endpunkten nicht akzeptiert, weder für Lese- noch für Schreibzugriffe; verwende ein org:admin-OAuth-Token.

Paginierung und Archivierung

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

Was this page helpful?

Voraussetzungen

Einen Workload zum Verwalten von WIF bootstrappen

Authentifizierung

Service-Accounts

Federation-Issuer

Federation-Regeln

Berechtigungen und Einschränkungen

Paginierung und Archivierung

Siehe auch

Voraussetzungen

Einen Workload zum Verwalten von WIF bootstrappen

Authentifizierung

Service-Accounts

Federation-Issuer

Federation-Regeln

Berechtigungen und Einschränkungen

Paginierung und Archivierung

Siehe auch

Voraussetzungen

Einen Workload zum Verwalten von WIF bootstrappen

Authentifizierung

Service-Accounts

Federation-Issuer

Federation-Regeln

Berechtigungen und Einschränkungen

Paginierung und Archivierung

Siehe auch

Voraussetzungen

Einen Workload zum Verwalten von WIF bootstrappen

Authentifizierung

Service-Accounts

Federation-Issuer

Federation-Regeln

Berechtigungen und Einschränkungen

Paginierung und Archivierung

Siehe auch