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 en distintas organizaciones en lugar de hacer clic a través de 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 scope org:admin. El scope se otorga únicamente a los miembros de la organización con el rol de admin, owner o primary owner, 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 scope org:admin (consulta Acceso de administrador), y luego exporta el token bearer. Iniciar sesión con --profile admin almacena la credencial org:admin bajo su propio nombre de perfil y también la convierte en el perfil activo de la CLI, y la variable exportada se aplica a cada llamada del SDK y de la CLI en ese shell; así que usa un shell que reserves para administración, elimina la variable cuando termines y vuelve a cambiar la CLI con ant profile activate default:

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_AUTH_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).

Los SDK y la CLI ant leen ANTHROPIC_AUTH_TOKEN automáticamente; deja ANTHROPIC_API_KEY sin definir en el mismo shell, porque estos endpoints rechazan las claves de API y algunos clientes prefieren la clave cuando ambas están definidas.

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 inicializar por sí misma. La siguiente sección recorre 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 scope org:admin, y deja que ese workload gestione los emisores de federación y cada regla de federación con alcance de workspace a través de esta API.

1. 1

   Crea la regla org:admin en la Console

   En la Claude Console, ve a Settings → Workload identity y selecciona Connect workload para crear una regla de federación para tu workload de automatización, por ejemplo un flujo de trabajo de GitHub Actions en tu repositorio de infraestructura. En Advanced rule options, establece el scope de OAuth de la regla en org:admin: el asistente entonces crea la nueva cuenta de servicio con el rol de organización Admin (o te pide que elijas una cuenta de servicio admin existente como destino).

2. 2

   Intercambia el token de identidad del workload

   Un workload que usa uno de los SDK o la CLI ant no realiza el intercambio por sí mismo. Apunta el cliente a la regla con las variables de entorno de federación y constrúyelo sin argumentos, exactamente como para la inferencia en Construye el cliente del SDK; el cliente intercambia el token de identidad en la primera solicitud y, antes de que expire el token de acceso resultante, vuelve a leer el token de identidad y lo intercambia de nuevo:

   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 solo es obligatorio si la regla está habilitada para todos
   # los workspaces o más de uno; los endpoints org:admin ignoran la vinculación.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   La CLI ant lee las mismas variables, o acepta los flags --federation-rule, --organization-id, --service-account-id e --identity-token-file. Para un workload que ejecuta más de un comando ant, usa un perfil de federación en lugar de flags o variables de entorno: con flags o variables la CLI intercambia el token de identidad de nuevo en cada proceso, y los tokens de identidad que llevan un claim jti (los tokens de GitHub Actions lo llevan) se aceptan solo una vez, por lo que un segundo comando sería rechazado; un perfil es también la única forma de darle a la CLI un workspace_id para el intercambio cuando la regla está habilitada para todos los workspaces o para más de uno, porque a diferencia de los SDK la CLI no pasa ANTHROPIC_WORKSPACE_ID ni --workspace-id al intercambio. Cada SDK también acepta las mismas configuraciones como argumentos explícitos del constructor, mostrados por lenguaje en Construye el cliente del SDK. Consulta Variables de entorno y Precedencia de credenciales para la lista completa y el orden.

   Un workload que llama a la API con curl intercambia el JWT por un token bearer org:admin de corta duración por sí mismo, usando el mismo intercambio de tokens que cualquier otro workload federado, y lo envía en el encabezado authorization: Bearer.

3. 3

   Gestiona emisores y reglas con alcance de workspace a través de la API

   Con el cliente configurado (o, para curl, el token emitido en ANTHROPIC_AUTH_TOKEN), el workload crea y gestiona tu configuración de federación usando los endpoints de esta página.

Para conocer las operaciones que un token emitido 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:

En los SDK estos endpoints son client.beta.organization.service_accounts, client.beta.organization.federation.issuers y client.beta.organization.federation.rules (ant beta:organization:service-accounts, federation:issuers y federation:rules en la CLI). Los ejemplos del SDK y de la CLI construyen el cliente predeterminado, que envía el token bearer desde ANTHROPIC_AUTH_TOKEN o, en un workload automatizado, realiza el intercambio de federación por sí mismo como se describe en Inicializa un workload para gestionar WIF. Los métodos de listado del SDK obtienen páginas adicionales bajo demanda, por lo que limit establece el tamaño de página; los ejemplos de PHP y Ruby leen una página.

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list()

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

Las claves de Admin API no se aceptan en estos endpoints; los ejemplos con 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.

Crea una cuenta de servicio:

client = anthropic.Anthropic()

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

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

Lista las cuentas de servicio:

client = anthropic.Anthropic()

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

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

Archiva una cuenta de servicio:

client = anthropic.Anthropic()

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

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

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 conocer los 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:

Registra un emisor. Este ejemplo registra GitHub Actions con descubrimiento de JWKS:

client = anthropic.Anthropic()

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

Lista los emisores:

client = anthropic.Anthropic()

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

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

Archiva un emisor:

client = anthropic.Anthropic()

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

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

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

Para conocer los 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 emitir 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 subrecurso /federation_rules/{rule_id}/workspaces. Se requiere workspace_id o applies_to_all_workspaces: true al crear.

Crea una regla. Este ejemplo permite que los despliegues de GitHub Actions desde la rama main actúen como la cuenta de servicio:

client = anthropic.Anthropic()

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

Lista las reglas, opcionalmente filtradas por emisor:

client = anthropic.Anthropic()

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

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

Archiva una regla:

client = anthropic.Anthropic()

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

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

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 emitir 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 conocer los 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 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 subrecurso de workspaces de una regla devuelve el conjunto completo sin paginación. Los recursos archivados se ocultan de los listados por defecto; pasa include_archived=true para incluirlos.

El archivado es una eliminación lógica 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.

Ver 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, scopes 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 de solicitud y respuesta generados para cada endpoint de la Admin API