Gérer WIF avec l'Admin API

L'Admin API vous permet de créer et de gérer par programmation les ressources de Workload Identity Federation : comptes de service, émetteurs de fédération et règles de fédération. Utilisez-la pour conserver votre configuration de fédération sous forme d'« infrastructure as code » (infrastructure en tant que code), la provisionner depuis la CI et la reproduire d'une organisation à l'autre au lieu de cliquer dans la Claude Console. Ces endpoints partagent le préfixe de chemin /v1/organizations avec le reste de l'Admin API.

Prérequis

Chaque requête de cette page s'authentifie avec un jeton bearer OAuth qui porte le scope org:admin. Ce scope n'est accordé qu'aux membres de l'organisation ayant le rôle admin, owner ou primary owner, et il donne accès à l'ensemble de l'organisation : toute liaison à un espace de travail est ignorée. Il existe deux façons d'obtenir un jeton, et elles confèrent des permissions différentes : un jeton issu de votre propre connexion agit en tant qu'utilisateur, tandis qu'un jeton fédéré agit en tant que compte de service et ne peut pas effectuer toutes les opérations de cette page.

Interactif (votre terminal)

Connectez-vous avec la CLI ant sous un profil dédié, en demandant le scope org:admin (voir Accès administrateur), puis exportez le jeton bearer. Se connecter avec --profile admin stocke l'identifiant org:admin sous son propre nom de profil et en fait également le profil actif de la CLI, et la variable exportée s'applique à chaque appel du SDK et de la CLI dans ce shell ; utilisez donc un shell que vous réservez à l'administration, supprimez la variable lorsque vous avez terminé, et rebasculez la CLI avec ant profile activate default :

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

Les jetons interactifs ont une courte durée de vie ; si les requêtes commencent à renvoyer 401, relancez la commande d'export (elle actualise automatiquement le jeton).

Les SDK et la CLI ant lisent automatiquement ANTHROPIC_AUTH_TOKEN ; laissez ANTHROPIC_API_KEY non défini dans le même shell, car ces endpoints rejettent les clés API et tous les clients utilisent la clé lorsque les deux sont définies.

Workload (CI et automatisation)

Créez une règle de fédération avec oauth_scope: org:admin qui cible un compte de service dont l'organization_role est admin. La règle elle-même doit être créée dans la Claude Console : accorder à un workload un accès administrateur de l'organisation est une action humaine délibérée, et non quelque chose que l'automatisation peut amorcer pour elle-même. La section suivante décrit cette configuration à effectuer une fois par organisation.

Amorcer un workload pour gérer WIF

Une seule règle créée dans la Console suffit pour placer le reste de votre configuration de fédération sous infrastructure as code : accordez le scope org:admin à un unique workload de confiance, et laissez ce workload gérer les émetteurs de fédération et toutes les règles de fédération limitées à un espace de travail via cette API.

1. 1

   Créer la règle org:admin dans la Console

   Dans la Claude Console, accédez à la page Workload identity (platform.claude.com/settings/workload-identity-federation) et sélectionnez Connect workload pour créer une règle de fédération pour votre workload d'automatisation, par exemple un workflow GitHub Actions dans votre dépôt d'infrastructure. Sous Advanced rule options, définissez le scope OAuth de la règle sur org:admin : l'assistant crée alors le nouveau compte de service avec le rôle d'organisation Admin (ou vous demande de choisir un compte de service admin existant comme cible).

2. 2

   Échanger le jeton d'identité du workload

   Un workload qui utilise l'un des SDK ou la CLI ant n'effectue pas l'échange lui-même. Pointez le client vers la règle avec les variables d'environnement de fédération et construisez-le sans arguments, exactement comme pour l'inférence dans Construire le client SDK ; le client échange le jeton d'identité lors de la première requête et, avant l'expiration du jeton d'accès obtenu, relit le jeton d'identité et l'échange à nouveau :

   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 n'est requis que si la règle est activée pour tous les
   # espaces de travail ou plusieurs ; les endpoints org:admin ignorent la liaison.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   La CLI ant lit les mêmes variables, ou accepte les options --federation-rule, --organization-id, --service-account-id et --identity-token-file. Pour un workload qui exécute plus d'une commande ant, utilisez un profil de fédération plutôt que des options ou des variables d'environnement : avec des options ou des variables, la CLI échange à nouveau le jeton d'identité dans chaque processus, et les jetons d'identité qui portent une claim jti (c'est le cas des jetons GitHub Actions) ne sont acceptés qu'une seule fois, de sorte qu'une deuxième commande serait rejetée ; un profil est également le seul moyen de fournir à la CLI un workspace_id pour l'échange lorsque la règle est activée pour tous les espaces de travail ou pour plusieurs d'entre eux, car contrairement aux SDK, la CLI ne transmet pas ANTHROPIC_WORKSPACE_ID ni --workspace-id à l'échange. Chaque SDK accepte également les mêmes paramètres sous forme d'arguments explicites du constructeur, présentés pour chaque langage dans Construire le client SDK. Consultez Variables d'environnement et Priorité des identifiants pour la liste complète et l'ordre de priorité.

   Un workload qui appelle l'API avec curl échange lui-même le JWT contre un jeton bearer org:admin de courte durée, en utilisant le même échange de jetons que tout autre workload fédéré, et l'envoie dans l'en-tête authorization: Bearer.

3. 3

   Gérer les émetteurs et les règles limitées à un espace de travail via l'API

   Une fois le client configuré (ou, pour curl, le jeton généré placé dans ANTHROPIC_AUTH_TOKEN), le workload crée et gère votre configuration de fédération à l'aide des endpoints de cette page.

Pour connaître les opérations qu'un jeton généré par un workload peut et ne peut pas effectuer, consultez Permissions et contraintes. Si vous avez déjà créé des émetteurs, des comptes de service ou des règles avec l'assistant Connect workload, listez-les avec les endpoints suivants et importez-les dans l'état de votre infrastructure as code au lieu de les recréer.

Authentification

Tous les endpoints se trouvent sous https://api.anthropic.com/v1/organizations/. Chaque requête vers les endpoints de fédération et de comptes de service nécessite l'en-tête de version de l'API et le jeton bearer :

Dans les SDK, ces endpoints sont client.organization.service_accounts, client.organization.federation.issuers et client.organization.federation.rules (ant organization:service-accounts, federation:issuers et federation:rules dans la CLI). Les exemples SDK et CLI construisent le client par défaut, qui envoie le jeton bearer depuis ANTHROPIC_AUTH_TOKEN ou, dans un workload automatisé, effectue lui-même l'échange de fédération comme décrit dans Amorcer un workload pour gérer WIF. Les méthodes de liste des SDK récupèrent les pages suivantes à la demande, donc limit définit la taille de page ; les exemples PHP et Ruby lisent une seule page.

client = anthropic.Anthropic()

service_accounts = client.organization.service_accounts.list()

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Les clés Admin API ne sont pas acceptées sur ces endpoints ; les exemples x-api-key de la page Admin API ne s'appliquent pas ici.

Comptes de service

Un compte de service (svac_...) est l'identité non humaine au nom de laquelle agit un jeton fédéré. Définissez organization_role sur developer.

Créer un compte de service :

client = anthropic.Anthropic()

service_account = client.organization.service_accounts.create(
    name="inference-worker", organization_role="developer"
)

print(f"id: {service_account.id}")
print(f"name: {service_account.name}")

Lister les comptes de service :

client = anthropic.Anthropic()

service_accounts = client.organization.service_accounts.list(limit=20)

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Archiver un compte de service :

client = anthropic.Anthropic()

service_account = client.organization.service_accounts.archive(
    "svac_01ABCDEFabcdef0123456789XY"
)

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

L'endpoint de création renvoie le nouveau compte de service :

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

Pour lire ou mettre à jour un compte de service individuel, utilisez GET et POST sur /v1/organizations/service_accounts/{service_account_id}. Un compte de service doit être membre d'un espace de travail avant que des jetons fédérés puissent y agir. Chaque compte de service dispose d'une appartenance implicite à l'espace de travail par défaut de votre organisation ; ajoutez des appartenances explicites à d'autres espaces de travail avec GET, POST et DELETE sur /v1/organizations/service_accounts/{service_account_id}/workspaces, où DELETE cible .../workspaces/{workspace_id}.

Pour le détail complet des paramètres et les schémas de réponse, consultez la référence de l'API Service accounts.

Émetteurs de fédération

Un émetteur de fédération (fdis_...) enregistre un fournisseur d'identité OIDC auprès de votre organisation. Le champ jwks est une union discriminée qui contrôle la manière dont Anthropic récupère les clés de signature du fournisseur :

Enregistrer un émetteur. Cet exemple enregistre GitHub Actions avec la découverte JWKS :

client = anthropic.Anthropic()

issuer = client.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}")

Lister les émetteurs :

client = anthropic.Anthropic()

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

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

Archiver un émetteur :

client = anthropic.Anthropic()

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

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

Pour lire ou mettre à jour un émetteur individuel, utilisez GET et POST sur /v1/organizations/federation_issuers/{issuer_id}. Un appelant OAuth ne peut pas mettre à jour un émetteur qui sous-tend une règle dont l'oauth_scope est autre que workspace:developer ou workspace:inference ; consultez Permissions et contraintes.

Pour le détail complet des paramètres et les schémas de réponse, consultez la référence de l'API Federation issuers.

Règles de fédération

Une règle de fédération (fdrl_...) lie un émetteur à un compte de service : les JWT de l'émetteur qui satisfont les conditions de correspondance de la règle peuvent générer des jetons qui agissent au nom de la cible de la règle. Le workspace_id de la requête de création active la règle dans cet espace de travail dès sa création ; ajoutez d'autres espaces de travail ultérieurement via la sous-ressource /federation_rules/{rule_id}/workspaces. workspace_id ou applies_to_all_workspaces: true est requis lors de la création.

Créer une règle. Cet exemple permet aux déploiements GitHub Actions depuis la branche main d'agir en tant que compte de service :

client = anthropic.Anthropic()

rule = client.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}")

Lister les règles, éventuellement filtrées par émetteur :

client = anthropic.Anthropic()

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

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

Archiver une règle :

client = anthropic.Anthropic()

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

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

L'endpoint de liste renvoie une page de règles et le curseur de la page suivante :

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

Pour lire ou mettre à jour une règle individuelle, utilisez GET et POST sur /v1/organizations/federation_rules/{rule_id}. Pour gérer les espaces de travail dans lesquels une règle peut générer des jetons, utilisez GET et POST sur /v1/organizations/federation_rules/{rule_id}/workspaces, et DELETE sur /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Pour le détail complet des paramètres et les schémas de réponse, consultez la référence de l'API Federation rules.

Permissions et contraintes

Une règle avec oauth_scope: org:admin doit cibler un compte de service dont l'organization_role est admin. Les noms de ressources doivent correspondre à ^[a-z0-9-]+$, comporter de 1 à 255 caractères et être uniques au sein d'une organisation pour chaque type de ressource ; pour l'ensemble des contraintes au niveau des champs, consultez Règles de validation.

Pagination et archivage

Les endpoints de liste des comptes de service, des émetteurs de fédération et des règles de fédération acceptent limit (de 1 à 100, 20 par défaut) et un curseur page issu de la réponse précédente. Transmettez la valeur next_page de la réponse comme paramètre de requête page lors de la requête suivante. La liste de la sous-ressource des espaces de travail d'une règle renvoie l'ensemble complet sans pagination. Les ressources archivées sont masquées des listes par défaut ; passez include_archived=true pour les inclure.

L'archivage est une suppression logique et il est idempotent : archiver une ressource déjà archivée réussit. L'archivage d'un émetteur ou d'un compte de service renvoie 400 tant qu'une règle de fédération active y fait encore référence ; archivez d'abord la règle.

Voir aussi

• Workload Identity Federation : concepts et guide de configuration dans la Console
• Référence WIF : variables d'environnement, règles de validation, scopes OAuth et codes d'erreur
• Admin API : le reste de la surface de gestion de l'organisation
• Référence de l'Admin API : schémas de requête et de réponse générés pour les endpoints de comptes de service et de fédération