Autenticación

La API de Claude admite tres formas de autenticar solicitudes:

Las claves de API y Workload Identity Federation otorgan el mismo acceso a los endpoints de la API de Claude. Elige claves de API para comenzar rápidamente: una clave personal para tu propio desarrollo, o una clave de cuenta de servicio para cualquier cosa compartida. Pasa a Workload Identity Federation cuando tu carga de trabajo ya tenga una identidad emitida por la plataforma que puedas federar. Usa App Attest para apps de iOS y macOS que distribuyas a usuarios finales.

Claves de API

Las claves de API son secretos estáticos que generas en la Claude Console y envías en cada solicitud como un token bearer en el encabezado Authorization.

Tipos de clave

Cuando creas una clave, eliges su tipo, que determina lo que la clave puede hacer, dónde funciona y cuándo deja de funcionar:

Las claves personales y las claves de cuenta de servicio están respaldadas por identidad: cada una pertenece a un usuario o cuenta de servicio que tu organización ya gestiona, y cada solicitud actúa como esa identidad. Cuando esa identidad se elimina de la organización, la clave deja de funcionar. Esto significa que las claves no sobrevivirán accidentalmente a las personas o cargas de trabajo que las poseen. Prefiérelas sobre las claves de workspace para nuevas integraciones.

Usa una clave personal para tu propio desarrollo y scripts. Una clave personal compartida actúa como una sola persona y se rompe cuando esa persona se va. Para cargas de trabajo compartidas o automatizadas (CI, servicios de producción), haz que un administrador de la organización cree una cuenta de servicio para que la carga de trabajo tenga su propia identidad.

Las claves de API de workspace aún funcionan, pero deben considerarse heredadas; se prefieren las claves respaldadas por identidad o Workload Identity Federation. Para migrar, consulta Reemplazar claves de API de workspace.

Crear y usar una clave

• Crear una clave: En la Claude Console, ve a la página API keys (platform.claude.com/settings/keys) y haz clic en Create key. Asigna un nombre a la clave y elige una expiración. Establece Linked account en ti mismo para una clave personal, o en una cuenta de servicio para una clave compartida entre varios usuarios. También puedes limitar la clave a un workspace específico, lo que te permite omitir la configuración manual de un ID de workspace en solicitudes futuras.
• Usar la clave: Envíala como Authorization: Bearer <key> en solicitudes HTTP directas, o establece la variable de entorno ANTHROPIC_API_KEY y los SDK de cliente la recogen automáticamente.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

El encabezado heredado x-api-key: YOUR_API_KEY todavía se admite en lugar de Authorization.

Almacena las claves de API en un gestor de secretos, rótalas periódicamente y deshabilita o elimina cualquier clave que sospeches que se ha filtrado. En la página de claves de API de la Claude Console, Disable es reversible (la Admin API informa el status de la clave como "inactive", y Re-enable lo devuelve a "active"), mientras que Delete es permanente: la clave se archiva y sigue apareciendo en List API Keys con status: "archived". Las claves expiradas solo se pueden eliminar. También puedes establecer una expiración al crear una clave para limitar cuánto tiempo sigue siendo utilizable una credencial filtrada.

client = Anthropic(api_key="my-anthropic-api-key")
# o, con ANTHROPIC_API_KEY configurada en el entorno:
client = Anthropic()

Seleccionar un workspace

Las claves de API que se crean para un workspace específico solo funcionan en ese workspace, y las solicitudes de API que usan estas claves pueden omitir el ID del workspace.

Si tu clave de API no está limitada a un workspace, debes especificar el ID del workspace en el encabezado anthropic-workspace-id para cada solicitud. Consulta el siguiente ejemplo para saber cómo establecer este encabezado en una solicitud o en los SDK.

La Admin API acepta una clave personal o una clave de cuenta de servicio solo si la clave no está limitada a un workspace específico.

Puedes encontrar el ID de un workspace en la columna ID de la página Workspaces (platform.claude.com/settings/workspaces) en la Claude Console, o llamando al endpoint List Workspaces. List Workspaces incluye el Default Workspace solo cuando pasas include_default=true; su ID también aparece en el encabezado de respuesta anthropic-workspace-id de cualquier solicitud que se ejecute allí.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Requerido en cada solicitud para una clave de varios espacios de trabajo.
# Omite extra_headers para una clave de un solo espacio de trabajo.
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# O configúralo una vez para cada solicitud de este cliente:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Si una solicitud realizada con una clave que no está limitada a un workspace omite el encabezado, la API devuelve un invalid_request_error 400:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Un valor de encabezado que no es un ID de workspace válido devuelve un invalid_request_error 400 con el mensaje anthropic-workspace-id header must be a valid workspace ID. Si el workspace no existe, o el usuario o la cuenta de servicio de la clave no tiene acceso a él, la API devuelve un not_found_error 404 con el mensaje Workspace `<id>` not found., la misma respuesta que para cualquier workspace desconocido.

Workload Identity Federation selecciona un workspace en el intercambio de tokens en su lugar; consulta la referencia de WIF para más detalles.

Expiración de claves

Cuando creas una clave de API desde la página de claves de API en la Claude Console, eliges una expiración: un preajuste (3 horas, 1 día, 7 días o 30 días), una duración personalizada, o Never para claves que almacenas en un gestor de secretos y rotas tú mismo. Si tu organización tiene una política de expiración máxima, la Console limita los preajustes y las duraciones personalizadas al máximo de la política, y Never no está disponible. Las claves existentes mantienen su comportamiento actual; la expiración se establece en el momento de la creación y no se puede cambiar después. La misma opción de expiración se aplica cuando creas una clave de Admin API en la Claude Console.

Anthropic envía un correo electrónico al creador de la clave a medida que se acerca la expiración: 7 días antes de la expiración para claves creadas con una vida útil de al menos 14 días, y 1 día antes para claves con una vida útil de al menos 7 días. Las claves con vidas útiles más cortas expiran sin un correo electrónico de advertencia.

Después de que una clave expira, las solicitudes realizadas con ella devuelven un 401 authentication_error. Crea una nueva clave para restaurar el acceso; las claves expiradas no se pueden reactivar.

La tabla de claves de API de la Console muestra la expiración de cada clave, y la Admin API informa la marca de tiempo expires_at de cada clave en los endpoints List API Keys y Retrieve API Key, para que puedas auditar y rotar las claves antes de que expiren. El campo es null para las claves sin expiración.

La expiración limita la vida útil de una credencial filtrada, pero no sustituye la higiene de secretos. Independientemente de la expiración, almacena las claves en un gestor de secretos y deshabilita o elimina cualquier clave que sospeches que se ha filtrado.

Reemplazar claves de API de workspace

Si tienes una clave de workspace, es posible que quieras reemplazarla con Workload Identity Federation o una clave personal o de cuenta de servicio. Esto proporciona mejor seguridad y observabilidad.

Consulta Workload Identity Federation para obtener detalles sobre cómo configurar Workload Identity Federation, que se prefiere sobre las claves de larga duración.

Para reemplazar una clave de workspace con una clave personal o de cuenta de servicio:

1. Decide el tipo de clave. Tu propio tooling debe usar una clave personal. Una carga de trabajo compartida o desatendida debe usar una clave de cuenta de servicio.
2. Crea una cuenta de servicio si es necesario. Es posible que tengas que pedir a un administrador de la organización que cree una en la página Service accounts (platform.claude.com/settings/service-accounts) en la Claude Console y la agregue al workspace correspondiente.
3. Crea la nueva clave. Créala específicamente para el workspace de la integración a menos que se necesiten varios workspaces.
4. Despliega la nueva clave. Reemplaza la clave antigua dondequiera que la integración la lea, típicamente la variable de entorno ANTHROPIC_API_KEY o una entrada del gestor de secretos. Para una clave de varios workspaces, también envía el encabezado anthropic-workspace-id como se muestra en Seleccionar un workspace.
5. Elimina la clave antigua. Confirma que las solicitudes se realizan correctamente y luego elimina la clave de workspace en la página de claves de API de la Claude Console.

Workload Identity Federation

Workload Identity Federation (WIF) permite que una carga de trabajo se autentique con un token de identidad de corta duración emitido por un proveedor de identidad (IdP) en el que ya confías, como AWS IAM, Google Cloud, o cualquier emisor OIDC que cumpla con los estándares (como GitHub Actions, cuentas de servicio de Kubernetes, SPIFFE, Microsoft Entra ID u Okta). La carga de trabajo intercambia su JWT emitido por el IdP en POST /v1/oauth/token por un token de acceso de corta duración de la API de Claude, y el SDK actualiza ese token automáticamente antes de que expire. No hay ninguna cadena sk-ant-api... que acuñar, distribuir o rotar.

La federación elimina las claves de API de Claude de larga duración de tu entorno, lo que reduce el radio de impacto de una credencial filtrada y te permite gestionar el acceso con los mismos controles de IdP que ya usas para los recursos en la nube. Por sí sola, no garantiza la seguridad de extremo a extremo: la cadena de confianza es tan fuerte como la configuración de tu proveedor de identidad, y un secreto de larga duración un salto más arriba (por ejemplo, una credencial estática en la nube que puede acuñar tokens de IdP) aún puede socavarla. Combina la federación con los controles de tu proveedor, como listas de permitidos de IP, MFA y registro de auditoría.

Para configurar la federación, creas tres recursos en la Claude Console (una cuenta de servicio, un emisor de federación y una regla de federación) y luego apuntas tu SDK a la regla. Consulta Workload Identity Federation para el recorrido completo de configuración.

App Attest

App Attest autentica apps de iOS y macOS que llaman a la API de Claude directamente desde el dispositivo. Cada instalación demuestra que es una compilación genuina y sin modificar de una app que registraste en la Claude Console, usando el servicio App Attest de Apple. Anthropic luego emite al dispositivo un token de acceso de corta duración que factura el uso a tu workspace. Los tokens están limitados a tu workspace, expiran después de una hora y autorizan solo llamadas a la API de Messages.

Para registrar tu app y obtener un ID de cliente, consulta App Attest para apps de iOS y macOS.

Próximos pasos