Autenticación

La Claude API admite tres formas de autenticar solicitudes:

Las claves de API y Workload Identity Federation otorgan el mismo acceso a los endpoints de la Claude API. 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 "API keys" (claves de API) son secretos estáticos que generas en la Claude Console y envías en cada solicitud en el encabezado x-api-key.

Tipos de clave

Cuando creas una clave, eliges su tipo, lo que determina qué puede hacer la clave, 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 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 deja de funcionar cuando esa persona se va. Para cargas de trabajo compartidas o automatizadas (CI, servicios de producción), pide a un administrador de la organización que cree una cuenta de servicio para que la carga de trabajo tenga su propia identidad.

Las claves de API de workspace siguen funcionando, 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: Ve a Settings → API keys en la Claude Console 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: Establece el encabezado x-api-key en solicitudes HTTP directas, o establece la variable de entorno ANTHROPIC_API_KEY y los SDK de cliente la detectan automáticamente.

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

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, Disable es reversible (la Admin API reporta el status de la clave como "inactive", y Re-enable la 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 permanece utilizable una credencial filtrada.

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

Seleccionar un workspace

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

Si tu clave de API no está limitada a un workspace, debes especificar el ID de workspace en el encabezado anthropic-workspace-id en cada solicitud. Consulta el siguiente ejemplo para ver 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 Settings → Workspaces en la Claude Console, o llamando al endpoint List Workspaces. Ninguno de los dos muestra el ID del Default Workspace: léelo del encabezado de respuesta anthropic-workspace-id de cualquier solicitud que se ejecute allí (por ejemplo, una realizada con una clave de workspace del Default Workspace), o de scope.workspace_id en dicha clave en List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Obligatorio en cada solicitud para una clave de múltiples espacios de trabajo.
# Omite extra_headers para una clave de un solo espacio de trabajo.
message = client.messages.create(
    model="claude-opus-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 400 invalid_request_error:

{
  "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 sea un ID de workspace válido devuelve un 400 invalid_request_error 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 404 not_found_error con el mensaje Workspace `<id>` not found., la misma respuesta que para cualquier workspace desconocido.

Workload Identity Federation, en cambio, selecciona un workspace en el intercambio de tokens; 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 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 expiración 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 expiración se establece en el momento de la creación y no se puede cambiar después. La misma elecció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 de advertencia.

Después de que una clave expira, las solicitudes realizadas con ella devuelven un 401 authentication_error. Crea una clave nueva 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 reporta 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 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, quizás quieras reemplazarla con Workload Identity Federation o con 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. Tus propias herramientas deben usar una clave personal. Una carga de trabajo compartida o no supervisada 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 Settings → Service accounts y la agregue al workspace correspondiente.
3. Crea la clave nueva. Créala específicamente para el workspace de la integración, a menos que se necesiten varios workspaces.
4. Despliega la clave nueva. Reemplaza la clave antigua dondequiera que la integración la lea, normalmente la variable de entorno ANTHROPIC_API_KEY o una entrada en un gestor de secretos. Para una clave de varios workspaces, envía también el encabezado anthropic-workspace-id como se muestra en Seleccionar un workspace.
5. Elimina la clave antigua. Confirma que las solicitudes se completan correctamente y luego elimina la clave de workspace en la página de claves de API.

Workload Identity Federation

Workload Identity Federation (federación de identidades de cargas de trabajo), o 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, 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 Claude API, y el SDK actualiza ese token automáticamente antes de que expire. No hay ninguna cadena sk-ant-api... que generar, distribuir o rotar.

La federación elimina las claves de larga duración de la Claude API de tu entorno, lo que reduce el radio de impacto de una credencial filtrada y te permite administrar el acceso con los mismos controles del 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 salto más arriba (por ejemplo, una credencial estática de la nube que puede generar tokens del IdP) aún puede socavarla. 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 ver la guía de configuración completa.

App Attest

App Attest autentica apps de iOS y macOS que llaman a la Claude API 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. Luego, Anthropic 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 únicamente 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