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 una identidad: cada una pertenece a un usuario o cuenta de servicio que tu organización ya administra, 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 sobreviven accidentalmente a las personas o cargas de trabajo que las poseen. Prefiérelas frente a las claves de espacio de trabajo 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

• Crea una clave: En la Claude Console, ve a la página de claves de API (platform.claude.com/settings/keys) y haz clic en Create key. Ponle un nombre a la clave y selecciona una caducidad. Configura Linked account contigo mismo para una clave personal, o con una cuenta de servicio para una clave compartida entre varios usuarios. También puedes limitar la clave a un espacio de trabajo específico, lo que te permite omitir la configuración manual de un ID de espacio de trabajo en solicitudes futuras.
• Usa la clave: Envíala como Authorization: Bearer <key> en solicitudes HTTP directas, o configura la variable de entorno ANTHROPIC_API_KEY y el SDK de cliente la detectará 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 caducadas solo pueden eliminarse. También puedes establecer una caducidad al crear una clave para limitar cuánto tiempo permanece 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 espacio de trabajo, debes especificar el ID del espacio de trabajo en el encabezado anthropic-workspace-id en cada solicitud. Consulta el siguiente ejemplo para ver cómo configurar este encabezado en una solicitud o en el 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

# Obligatorio en cada solicitud para una clave que no esté limitada a un workspace.
# Omite extra_headers para una clave limitada a un solo workspace.
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": "This API key is not scoped to a workspace, so this request must include the anthropic-workspace-id header with the ID of the workspace to use. Add the header, or use an API key that is scoped to a workspace."
  },
  "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 de la Claude Console, eliges una caducidad: un valor predefinido (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 caducidad máxima, la Console limita los valores predefinidos y las duraciones personalizadas al máximo de la política, y Never no está disponible. Las claves existentes mantienen su comportamiento actual; la caducidad se establece en el momento de la creación y no puede cambiarse después. La misma opción de caducidad 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 la referencia de WIF para obtener detalles sobre cómo configurar Workload Identity Federation, que se prefiere frente a 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) de la Claude Console y la agregue al espacio de trabajo correspondiente.
3. Crea la clave nueva. Créala específicamente para el espacio de trabajo de la integración, a menos que la integración necesite varios espacios de trabajo.
4. Implementa la clave nueva. Reemplaza la clave anterior dondequiera que la integración la lea, normalmente la variable de entorno ANTHROPIC_API_KEY o una entrada de un gestor de secretos. Para una clave que no está limitada a un espacio de trabajo, envía también el encabezado anthropic-workspace-id como se muestra en Seleccionar un espacio de trabajo.
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 "identity provider" (proveedor de identidad), o IdP, en el que ya confías. Estos IdP incluyen AWS IAM, Google Cloud y 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 caduque. No hay ninguna cadena sk-ant-api... que generar, distribuir o rotar.

La federación elimina las claves de API de Claude de larga duración de tu entorno, lo que limita el daño que puede causar una credencial filtrada y te permite administrar 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 sólida como la configuración de tu proveedor de identidad, y un secreto de larga duración un paso antes en esa cadena (por ejemplo, una credencial de nube estática que puede generar tokens del IdP) aún puede comprometerla. Combina la federación con los controles de tu proveedor, como listas de IP permitidas, MFA y registros 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 no modificada de una app que registraste en la Claude Console, usando el servicio App Attest de Apple. Luego, Anthropic emite al dispositivo un token de acceso de corta duración que factura el uso a tu espacio de trabajo. Los tokens están limitados a tu espacio de trabajo, caducan después de 1 hora y autorizan solo llamadas a la Messages API.

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

Próximos pasos