Autenticar llamadas a la API de Claude con la cabecera x-api-key
Cada solicitud a la API de Claude tiene que demostrar quién está llamando antes de que el servidor haga nada más.
Esa prueba es una única cabecera: x-api-key, que lleva tu clave de API.
Esta página cubre dónde obtener una clave, cómo configurarla para el SDK de Python y cómo enviarla manualmente cuando no estés usando el SDK.
Resumen
La cabecera x-api-key es cómo la API de Claude autentica cada solicitud, comprobada antes de que se inspeccione el cuerpo de la solicitud.
El SDK oficial de Python lee tu clave de la variable de entorno ANTHROPIC_API_KEY por defecto, por lo que la mayoría del código nunca toca la cabecera directamente.
También puedes pasar la clave explícitamente al constructor del cliente, lo cual es útil para configuraciones de múltiples claves o rotación de claves por solicitud.
Los llamadores HTTP sin procesar (curl, requests, o el cliente HTTP de otro idioma) deben establecer x-api-key ellos mismos, junto con un par de otras cabeceras requeridas.
Tratar las claves de API como cualquier otro secreto, nunca codificadas, nunca comprometidas, rotadas según un horario, es la diferencia entre un susto menor y un incidente real.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
import os
import anthropic
# Opción 1: implícita - el SDK lee ANTHROPIC_API_KEY del entorno
client = anthropic.Anthropic()
# Opción 2: explícita - pasa la clave directamente
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])Cuándo usar esto:
- Al configurar un nuevo proyecto: usa el enfoque de variable de entorno (Opción 1).
- Al admitir múltiples cuentas o rotación de claves en un solo proceso: usa el argumento explícito
api_key(Opción 2). - Al llamar a la API sin el SDK: establece la cabecera
x-api-keymanualmente (ver Ejemplo de funcionamiento). - Al ejecutar en CI o en un contenedor: inyecta
ANTHROPIC_API_KEYa través del mecanismo de secretos de tu plataforma, no un archivo subido.
Ejemplo de funcionamiento
import os
import anthropic
def get_client() -> anthropic.Anthropic:
api_key = os.environ.get("ANTHROPIC_API_KEY")
if not api_key:
raise RuntimeError(
"ANTHROPIC_API_KEY no está configurada. Expórtala antes de ejecutar este script."
)
return anthropic.Anthropic(api_key=api_key)
def main() -> None:
client = get_client()
response = client.messages.create(
model="claude-sonnet-5-20260630",
max_tokens=100,
messages=[{"role": "user", "content": "Confirma que la autenticación está funcionando."}],
)
print(response.content[0].text)
if __name__ == "__main__":
main()Lo que esto demuestra:
- Fallar rápidamente con un mensaje de error claro cuando la clave falta, en lugar de dejar que un críptico
401aparezca más tarde. - Leer la clave del entorno explícitamente, lo que hace que la dependencia sea visible en la parte superior del script.
- Pasar
api_keyexplícitamente al constructor, lo que funciona de manera idéntica a dejar que el SDK lea la variable de entorno por sí mismo.
Profundización
Cómo funciona
- El constructor
anthropic.Anthropic()del SDK busca primero un argumento explícitoapi_key; si no se proporciona ninguno, recurre a leerANTHROPIC_API_KEYdel entorno del proceso. - Internamente, el SDK adjunta tu clave como la cabecera
x-api-keyen cada solicitud HTTPS saliente, nunca tienes que configurarla por llamada. - El servidor valida esta cabecera antes de analizar el resto del cuerpo de la solicitud, por lo que los fallos de autenticación se devuelven rápidamente e independientemente de si tu prompt o parámetros son válidos.
- Una clave faltante o inválida genera
anthropic.AuthenticationErroren Python, mapeada desde una respuesta HTTP401.
HTTP sin procesar sin el SDK
Si estás llamando a la API directamente (para un idioma sin SDK, o para depurar a nivel HTTP), configura la cabecera tú mismo:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-01-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-20260630",
"max_tokens": 100,
"messages": [{"role": "user", "content": "Hola"}]
}'Ten en cuenta que las llamadas sin procesar necesitan tanto la cabecera x-api-key como una cabecera anthropic-version; el SDK establece la cabecera de versión automáticamente por ti.
Opciones de almacenamiento de claves
| Enfoque | Ideal para | Riesgo |
|---|---|---|
Archivo .env + python-dotenv, ignorado por git | Desarrollo local | Compromiso accidental si .gitignore está mal configurado |
| Gestor de secretos de plataforma (por ejemplo, un almacén de secretos en la nube, variables secretas de CI) | Producción, CI/CD | Requiere configuración inicial, pero es la opción más segura a largo plazo |
| Cadena codificada en código fuente | Nunca | La clave se filtra al control de versiones, a los registros y a cualquiera con acceso al repositorio |
Notas de Python
# Prefiere os.environ[...] (genera KeyError ruidosamente) sobre os.environ.get(...)
# con un fallback silencioso a None, cuando la clave es genuinamente requerida:
import os
api_key = os.environ["ANTHROPIC_API_KEY"] # genera un error claramente si faltaTrampas
- Codificar la clave en el código fuente. Termina en el historial del control de versiones de forma permanente, incluso si la eliminas en un commit posterior. Solución: usa variables de entorno o un gestor de secretos, y añade
.enva.gitignoreantes del primer commit que lo toque. - Subir un archivo
.envpor accidente. Una entrada.gitignorefaltante o mal configurada filtra silenciosamente la clave. Solución: añade.enva.gitignoreprimero, y luego verifica congit statusque no está rastreado antes de tu primer commit. - Confundir
401(clave incorrecta) con403(clave válida, sin permiso). Ambos son errores de la etapa de autenticación pero necesitan soluciones diferentes. Solución: comprueba el código de estado de la excepción;401significa regenerar o corregir la clave,403significa comprobar los permisos/alcance de la clave en tu cuenta. - Registrar el objeto de solicitud completo, incluidas las cabeceras, en la salida de depuración. Esto puede filtrar la clave a archivos de registro o herramientas de observabilidad. Solución: depura u omite la cabecera
x-api-keyal registrar solicitudes. - Compartir una clave en todos los entornos (dev, staging, prod). Una fuga o error en un entorno compromete a todos ellos. Solución: emite claves separadas por entorno para poder revocar una sin afectar a las demás.
- Olvidar la cabecera
anthropic-versionen llamadas HTTP sin procesar. Los llamadores sin procesar a veces copian la cabecera de autenticación pero olvidan esta, causando fallos confusos no relacionados con la autenticación en sí. Solución: envía siempre ambas cabeceras juntas para llamadas que no sean del SDK.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
Variable de entorno (ANTHROPIC_API_KEY) + recogida implícita del SDK | Aplicaciones de clave única, desarrollo local, la mayoría de los servicios de producción | Necesitas múltiples claves activas en un solo proceso |
Argumento api_key explícito por instancia de cliente | Aplicaciones multi-inquilino, rotación de claves, claves por cliente | Una clave estática única cubre tu caso de uso; añade complejidad innecesaria |
| Gestor de secretos inyectando la variable de entorno en el momento del despliegue | Producción y CI/CD | Desarrollo local, donde un archivo .env es más simple |
Preguntas frecuentes
¿Tengo que configurar la cabecera x-api-key manualmente cuando uso el SDK de Python?
No. anthropic.Anthropic() la adjunta automáticamente desde la variable de entorno ANTHROPIC_API_KEY o un argumento explícito api_key; solo configuras la cabecera tú mismo para llamadas HTTP sin procesar.
¿Qué sucede si ANTHROPIC_API_KEY no está configurada y no paso api_key explícitamente?
El SDK genera un error cuando intentas construir el cliente o hacer una llamada, ya que no tiene una clave para enviar.
¿Cuál es la diferencia entre una respuesta 401 y 403?
401significa que la clave en sí falta, está mal formada o es inválida.403significa que la clave es válida pero no tiene permiso para lo que intentas hacer.
¿Puedo usar una clave de API diferente para diferentes partes de mi aplicación?
Sí, instancia múltiples clientes anthropic.Anthropic(api_key=...), cada uno con su propia clave, en lugar de depender de una única variable de entorno compartida.
¿Es seguro poner mi clave de API directamente en mi script de Python para una prueba rápida?
Solo para una prueba local desechable que nunca subirás; incluso entonces, una variable de entorno es igual de rápida de configurar y evita el riesgo de un commit accidental.
¿Qué cabecera necesitan los llamadores HTTP sin procesar además de x-api-key?
Una cabecera anthropic-version que especifica la versión de la API y una cabecera content-type: application/json para el cuerpo de la solicitud.
¿Debo rotar mi clave de API según un horario?
Sí, trátala como cualquier credencial; rotarla periódicamente limita la ventana de daño si una clave se expone sin tu conocimiento.
¿Cómo evito filtrar mi clave a través del registro?
Depura las cabeceras antes de registrar objetos de solicitud completos, y evita registrar volcados de solicitud/respuesta sin procesar en producción sin redacción.
¿Puedo revocar una sola clave de API sin afectar a otras?
Sí, este es exactamente el motivo por el que las claves separadas por entorno o por servicio valen el costo de configuración; una clave comprometida puede ser revocada de forma aislada.
¿La cabecera x-api-key cambia entre solicitudes de streaming y no streaming?
No, la autenticación es idéntica en ambos casos; solo el campo stream en el cuerpo de la solicitud y la forma de la respuesta difieren.
¿Cuál es la forma más segura de almacenar una clave para el desarrollo local?
Un archivo .env ignorado por git cargado con una biblioteca como python-dotenv, mantenido fuera del control de versiones desde el primer commit.
Relacionado
- Comprender el ciclo de vida de las solicitudes de la API de Claude - dónde encaja la autenticación en el flujo general de la solicitud.
- Instalar y configurar el SDK de Python de Anthropic - configuración del cliente más allá de la clave.
- Referencia de códigos de error y solución de problemas de la API de Claude - lista completa de códigos de error relacionados con la autenticación.
- Crear un wrapper reutilizable para el cliente de la API de Claude - centralizar el manejo de claves en una aplicación.
Versiones de pila: Escrito contra la línea de modelos de Claude actual a partir de aproximadamente junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.