Gérer WIF avec l'Admin API

L'Admin API vous permet de créer et de gérer les ressources de Workload Identity Federation de manière programmatique : 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 dans l'infrastructure as code, la provisionner depuis la CI et la reproduire entre organisations au lieu de naviguer dans la Claude Console. Ces points de terminaison partagent le préfixe de chemin /v1/organizations avec le reste de l'Admin API.



Prérequis

Chaque requête sur cette page s'authentifie avec un jeton porteur OAuth qui porte la portée org:admin. La portée n'est accordée qu'aux membres de l'organisation ayant le rôle admin, owner ou primary owner, et elle accorde l'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 portent 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 la portée org:admin (voir Accès administrateur), puis exportez le jeton porteur :

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

Les jetons interactifs ont une durée de vie courte ; si les requêtes commencent à renvoyer 401, réexécutez la commande d'exportation (elle rafraîchit le jeton automatiquement).



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 le organization_role est admin. La règle elle-même doit être créée dans la Claude Console : accorder à un workload l'accès administrateur de l'organisation est une action humaine délibérée, pas 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 à un seul workload de confiance la portée org:admin, et laissez ce workload gérer les émetteurs de fédération et chaque règle de fédération limitée à un espace de travail via cette API.

Pour les opérations qu'un jeton émis par un workload peut et ne peut pas effectuer, voir 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 points de terminaison suivants et importez-les dans votre état d'infrastructure-as-code au lieu de les recréer.



Authentification

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

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"

Les clés Admin API ne sont pas acceptées sur ces points de terminaison ; 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 en tant que laquelle un jeton fédéré agit. Définissez organization_role sur developer.

# Créer un compte de service
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"
  }'

# Lister les comptes de service
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"

# Archiver un compte de service
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"

Le point de terminaison 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 seul compte de service, 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 les jetons fédérés puissent y agir. Chaque compte de service a une appartenance implicite à l'espace de travail par défaut de votre organisation ; ajoutez des appartenances explicites pour 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 les détails complets des paramètres et les schémas de réponse, voir la référence de l'API des comptes de service.



É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 façon dont Anthropic récupère les clés de signature du fournisseur :

# Enregistrer un émetteur (GitHub Actions, avec découverte JWKS)
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"}
  }'

# Lister les émetteurs
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"

# Archiver un émetteur
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"

Pour lire ou mettre à jour un seul émetteur, utilisez GET et POST sur /v1/organizations/federation_issuers/{issuer_id}. Un appelant OAuth ne peut pas mettre à jour un émetteur qui soutient une règle dont le oauth_scope est autre chose que workspace:developer ou workspace:inference ; voir Permissions et contraintes.

Pour les détails complets des paramètres et les schémas de réponse, voir la référence de l'API des émetteurs de fédération.



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 émettre des jetons qui agissent en tant que cible de la règle. Le workspace_id dans la requête de création active la règle dans cet espace de travail à la création ; ajoutez d'autres espaces de travail plus tard via la sous-ressource /federation_rules/{rule_id}/workspaces. Soit workspace_id, soit applies_to_all_workspaces: true est requis à la création.

# Créer une règle (GitHub Actions déploie depuis la branche main)
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
  }'

# Lister les règles, avec filtrage optionnel par émetteur
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"

# Archiver une règle
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"

Le point de terminaison de liste renvoie une page de règles et le curseur pour la page suivante :

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

Pour lire ou mettre à jour une seule règle, utilisez GET et POST sur /v1/organizations/federation_rules/{rule_id}. Pour gérer les espaces de travail dans lesquels une règle peut émettre 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 les détails complets des paramètres et les schémas de réponse, voir la référence de l'API des règles de fédération.



Permissions et contraintes

Une règle avec oauth_scope: org:admin doit cibler un compte de service dont le 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 les contraintes complètes au niveau des champs, voir Règles de validation.



Pagination et archivage

Les points de terminaison de liste des comptes de service, des émetteurs de fédération et des règles de fédération acceptent limit (1 à 100, 20 par défaut) et un curseur page tiré de la réponse précédente. Passez 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 logicielle et est idempotent : archiver une ressource déjà archivée réussit. Archiver un émetteur ou 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, portées 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 chaque point de terminaison de l'Admin API