Gestiona WIF con la Admin API

La Admin API te permite crear y gestionar recursos de Workload Identity Federation de forma programática: cuentas de servicio, emisores de federación y reglas de federación. Úsala para mantener tu configuración de federación en infraestructura como código, aprovisionarla desde CI y reproducirla entre organizaciones en lugar de hacer clics en la Claude Console. Estos endpoints comparten el prefijo de ruta /v1/organizations con el resto de la Admin API.



Requisitos previos

Cada solicitud en esta página se autentica con un token bearer de OAuth que lleva el alcance org:admin. El alcance se otorga solo a los miembros de la organización con el rol de administrador, propietario o propietario principal, y otorga acceso a toda la organización: cualquier vinculación a un workspace se ignora. Hay dos formas de obtener un token, y conllevan permisos diferentes: un token de tu propio inicio de sesión actúa como un usuario, mientras que un token federado actúa como una cuenta de servicio y no puede realizar todas las operaciones de esta página.



Interactivo (tu terminal)

Inicia sesión con la CLI ant bajo un perfil dedicado, solicitando el alcance org:admin (consulta Acceso de administrador), y luego exporta el token bearer:

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

Los tokens interactivos son de corta duración; si las solicitudes comienzan a devolver 401, vuelve a ejecutar el comando de exportación (actualiza el token automáticamente).



Workload (CI y automatización)

Crea una regla de federación con oauth_scope: org:admin que apunte a una cuenta de servicio cuyo organization_role sea admin. La regla en sí debe crearse en la Claude Console: otorgar a un workload acceso de administrador de la organización es una acción humana deliberada, no algo que la automatización pueda iniciar por sí misma. La siguiente sección te guía por esta configuración que se realiza una vez por organización.



Inicializa un workload para gestionar WIF

Una sola regla creada en la Console es suficiente para poner el resto de tu configuración de federación bajo infraestructura como código: otorga a un único workload de confianza el alcance org:admin, y deja que ese workload gestione los emisores de federación y todas las reglas de federación con alcance de workspace a través de esta API.

Para conocer las operaciones que un token acuñado por un workload puede y no puede realizar, consulta Permisos y restricciones. Si ya creaste emisores, cuentas de servicio o reglas con el asistente Connect workload, lístalos con los siguientes endpoints e impórtalos a tu estado de infraestructura como código en lugar de recrearlos.



Autenticación

Todos los endpoints se encuentran bajo https://api.anthropic.com/v1/organizations/. Cada solicitud a los endpoints de federación y de cuentas de servicio necesita el encabezado de versión de la API y el token bearer:

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"

Las claves de la Admin API no se aceptan en estos endpoints; los ejemplos de x-api-key de la página de la Admin API no aplican aquí.



Cuentas de servicio

Una cuenta de servicio (svac_...) es la identidad no humana como la que actúa un token federado. Establece organization_role en developer.

# Crear una cuenta de servicio
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"
  }'

# Listar cuentas de servicio
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"

# Archivar una cuenta de servicio
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"

El endpoint de creación devuelve la nueva cuenta de servicio:

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

Para leer o actualizar una sola cuenta de servicio, usa GET y POST en /v1/organizations/service_accounts/{service_account_id}. Una cuenta de servicio debe ser miembro de un workspace antes de que los tokens federados puedan actuar en él. Cada cuenta de servicio tiene una membresía implícita en el workspace predeterminado de tu organización; agrega membresías explícitas para otros workspaces con GET, POST y DELETE en /v1/organizations/service_accounts/{service_account_id}/workspaces, donde DELETE apunta a .../workspaces/{workspace_id}.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de cuentas de servicio.



Emisores de federación

Un emisor de federación (fdis_...) registra un proveedor de identidad OIDC en tu organización. El campo jwks es una unión discriminada que controla cómo Anthropic obtiene las claves de firma del proveedor:

# Registrar un emisor (GitHub Actions, con descubrimiento de 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"}
  }'

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

# Archivar un emisor
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"

Para leer o actualizar un solo emisor, usa GET y POST en /v1/organizations/federation_issuers/{issuer_id}. Un llamador de OAuth no puede actualizar un emisor que respalda una regla cuyo oauth_scope sea cualquier cosa distinta de workspace:developer o workspace:inference; consulta Permisos y restricciones.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de emisores de federación.



Reglas de federación

Una regla de federación (fdrl_...) vincula un emisor a una cuenta de servicio: los JWT del emisor que satisfacen las condiciones de coincidencia de la regla pueden acuñar tokens que actúan como el destino de la regla. El workspace_id en la solicitud de creación habilita la regla en ese workspace al momento de la creación; agrega más workspaces después a través del sub-recurso /federation_rules/{rule_id}/workspaces. Se requiere workspace_id o applies_to_all_workspaces: true al crear.

# Crear una regla (GitHub Actions despliega desde la rama 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
  }'

# Listar reglas, opcionalmente filtradas por emisor
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"

# Archivar una regla
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"

El endpoint de listado devuelve una página de reglas y el cursor para la página siguiente:

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

Para leer o actualizar una sola regla, usa GET y POST en /v1/organizations/federation_rules/{rule_id}. Para gestionar los workspaces en los que una regla puede acuñar tokens, usa GET y POST en /v1/organizations/federation_rules/{rule_id}/workspaces, y DELETE en /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de reglas de federación.



Permisos y restricciones

Una regla con oauth_scope: org:admin debe apuntar a una cuenta de servicio cuyo organization_role sea admin. Los nombres de los recursos deben coincidir con ^[a-z0-9-]+$, tener de 1 a 255 caracteres y ser únicos dentro de una organización para cada tipo de recurso; para conocer las restricciones completas a nivel de campo, consulta Reglas de validación.



Paginación y archivado

Los endpoints de listado de cuentas de servicio, emisores de federación y reglas de federación aceptan limit (de 1 a 100, 20 por defecto) y un cursor page tomado de la respuesta anterior. Pasa el valor next_page de la respuesta como el parámetro de consulta page en la siguiente solicitud. El listado del sub-recurso de workspaces de reglas devuelve el conjunto completo sin paginación. Los recursos archivados se ocultan de los listados de forma predeterminada; pasa include_archived=true para incluirlos.

El archivado es una eliminación suave y es idempotente: archivar un recurso ya archivado tiene éxito. Archivar un emisor o una cuenta de servicio devuelve 400 mientras una regla de federación activa todavía lo referencie; archiva primero la regla.



Consulta también

• Workload Identity Federation: conceptos y el recorrido de configuración en la Console
• Referencia de WIF: variables de entorno, reglas de validación, alcances de OAuth y códigos de error
• Admin API: el resto de la superficie de gestión de la organización
• Referencia de la Admin API: esquemas generados de solicitud y respuesta para cada endpoint de la Admin API