Clave API de Anthropic (2026): cómo obtenerla, tipos de clave, Claude Code y errores

Clave API de Anthropic (2026): cómo obtenerla, tipos de clave, Claude Code y errores

Para obtener una clave API de Anthropic, inicia sesión en Claude Console, abre API keys, haz clic en Create key, elige un nombre, una caducidad y una cuenta vinculada (tú o una cuenta de servicio) y copia la clave que empieza por sk-ant-, porque Console solo la muestra una vez. Añade un método de pago o créditos antes de llamar a la API: el uso se factura por token y las cuentas nuevas solo reciben un pequeño crédito de prueba gratuito, según la página de precios de Anthropic a 22 de octubre de 2026. La misma clave sirve para todos los modelos Claude; no existe una "clave de Claude API" ni una "clave de Sonnet" aparte.

Esta guía es para desarrolladores que necesitan una clave para scripts, agentes de programación como Claude Code o un servicio en producción. Cubre los tipos de clave de 2026 (personal, de cuenta de servicio y la clave de workspace heredada), las reglas de caducidad, la cabecera anthropic-workspace-id que hace fallar muchas primeras peticiones, código funcional, los errores 401/400/429 más comunes y cuándo conviene una sola clave para varios proveedores.

La clave API de Anthropic en 60 segundos

Paso	Dónde	Qué debes saber (comprobado el 22 oct 2026)
1. Iniciar sesión	platform.claude.com	Las claves API están en Claude Console, no en la app de chat claude.ai
2. Abrir API keys	Settings → API keys	Si Create key aparece en gris, tu rol no puede crear claves
3. Crear la clave	Nombre, caducidad, cuenta vinculada, workspace opcional	Opciones de caducidad: 3 horas, 1 día, 7 días, 30 días, personalizada o Never
4. Copiar una sola vez	Solo se muestra al crearla	Empieza por sk-ant-; si la pierdes no podrás volver a verla
5. Añadir facturación	Settings → Billing	Pago por uso en USD; cada nivel tiene un límite de gasto mensual
6. Probar	POST https://api.anthropic.com/v1/messages	Envía la clave como Authorization: Bearer (o el antiguo x-api-key)

Fuente: documentación de Anthropic Get your Claude API key y Authentication, comprobada el 22 de octubre de 2026.

Paso a paso: crea tu clave API de Anthropic

1. Crea una cuenta de Console o inicia sesión en platform.claude.com. La suscripción de chat de Claude y la API se facturan por separado, aunque los planes Max incluyen un crédito mensual de API (detalles más abajo y en nuestra guía de precios de la API de Anthropic).
2. Abre la página API keys. Si tu organización tiene varios workspaces, puedes elegir uno para limitar la clave a él.
3. Haz clic en Create key y rellena tres campos: un nombre descriptivo (por ejemplo ci-staging-claude), una caducidad y la Linked account. Vincularla a ti crea una clave personal; vincularla a una cuenta de servicio crea una clave para cargas de trabajo compartidas.
4. Copia la clave de inmediato. La documentación de Anthropic indica que la clave completa solo se muestra una vez. Guárdala en un gestor de contraseñas o de secretos, nunca en un repositorio Git.
5. Añade créditos o una tarjeta en la página Billing. Sin saldo, tu primera petición fallará aunque la clave sea válida.
6. Expórtala como variable de entorno para que los SDK la lean automáticamente:

export ANTHROPIC_API_KEY="sk-ant-api03-..."   # macOS/Linux, current shell only
# Windows PowerShell:
# setx ANTHROPIC_API_KEY "sk-ant-api03-..."

¿Qué tipo de clave deberías elegir?

En 2026 Anthropic distingue tres tipos de clave. Elegir el equivocado es la causa más habitual de que una clave "deje de funcionar de repente" cuando alguien abandona el equipo.

Tipo de clave	Actúa como	Deja de funcionar cuando	Úsala para
Clave personal	Tú, con tus roles	Sales de la organización, o una clave de un solo workspace pierde ese workspace	Desarrollo local, tus scripts, tu propio Claude Code
Clave de cuenta de servicio	Una cuenta de servicio	La cuenta de servicio se archiva o se retira del workspace	Pipelines de CI, servicios en producción, agentes compartidos
Clave de workspace (heredada)	Nadie (pertenece al workspace)	Caduca, se desactiva/elimina o se archiva el workspace	Solo integraciones existentes; conviene migrar

Datos de la página Authentication de Anthropic, 22 de octubre de 2026. Anthropic recomienda claves personales o de cuenta de servicio porque están respaldadas por una identidad y no pueden sobrevivir a la persona o carga de trabajo que las posee. Para producción en AWS, Google Cloud, Azure, GitHub Actions o Kubernetes, la misma página recomienda Workload Identity Federation, que sustituye las claves estáticas por tokens de corta duración.

Reglas de caducidad que conviene conocer

• La caducidad se elige al crear la clave y no se puede cambiar después.
• Anthropic envía un correo al creador 7 días antes del vencimiento en claves con una vida de al menos 14 días, y 1 día antes en claves de al menos 7 días; las claves más cortas caducan sin aviso.
• Tras caducar, las peticiones devuelven 401 authentication_error, y las claves caducadas no se pueden reactivar, solo eliminar.
• Disable es reversible; Delete es permanente.

Un patrón práctico: claves de 30 días para portátiles y agentes de programación, y claves de cuenta de servicio guardadas en un gestor de secretos (con rotación) para servidores. Nuestras guías sobre gestión segura de claves API para productos de IA y rotación de claves detrás de un gateway profundizan en ello.

Prueba tu clave: primera petición con curl, Python y Node.js

El ID de modelo usado abajo, claude-sonnet-5-5, es el modelo Sonnet actual en el resumen de modelos de Anthropic a 22 de octubre de 2026.

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Reply with the word ok if this key works."}]
  }'

# pip install anthropic
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Reply with the word ok if this key works."}],
)
print(next(b.text for b in msg.content if b.type == "text"))
print("tokens:", msg.usage.input_tokens, "in /", msg.usage.output_tokens, "out")

// npm install @anthropic-ai/sdk
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const msg = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 256,
  messages: [{ role: "user", content: "Reply with the word ok if this key works." }],
});
console.log(msg.content.find((b) => b.type === "text")?.text);

Una prueba así cuesta una fracción de céntimo: con el precio oficial de Sonnet 5.5 de 2 $ por millón de tokens de entrada y 10 $ por millón de salida (precios de Anthropic, 22 de octubre de 2026), 30 tokens de entrada y 5 de salida cuestan unos 0,0001 $.

La cabecera de workspace que rompe las primeras peticiones

Si tu clave no está limitada a un workspace, cada petición debe incluir anthropic-workspace-id; si no, la API devuelve 400 invalid_request_error con el mensaje "This API key is not scoped to a workspace...". Encontrarás el ID en la página Workspaces de Console. La solución en Python:

client = anthropic.Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_..."}  # only for keys not scoped to a workspace
)

Las claves creadas para un único workspace pueden omitir la cabecera, por eso Anthropic sugiere limitarlas al crearlas (documentación de Authentication).

Usa tu clave API de Anthropic con Claude Code

Claude Code puede autenticarse con una suscripción de claude.ai, un inicio de sesión en Console, un proveedor cloud o una clave API. Según la documentación de autenticación de Claude Code, comprobada el 22 de octubre de 2026:

• Si ANTHROPIC_API_KEY está definida, Claude Code pregunta en el primer arranque si quieres usarla y omite el inicio de sesión en el navegador cuando la apruebas.
• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN y el ajuste apiKeyHelper se aplican a la CLI, la extensión de VS Code, el Agent SDK y GitHub Actions, pero no a Claude Desktop ni a las sesiones en la nube.
• apiKeyHelper ejecuta un script que devuelve una clave, útil para obtener una clave de corta duración desde un vault. Si el script falla tres veces, las peticiones fallan.
• Los usuarios de Console ya pueden iniciar sesión sin crear una clave API (Claude Code v2.1.242 o posterior), lo que guarda un perfil OAuth en lugar de una clave estática. Elimina ANTHROPIC_API_KEY antes de hacerlo.

export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude        # approve the key when prompted
# inside Claude Code, /status shows which credential is active

Si Claude Code muestra errores de token o de inicio de sesión, consulta nuestra guía de errores de token de autenticación en Claude Code. Para apuntar Claude Code a un router en lugar de a Anthropic directamente, mira configurar un router de API para Claude Code.

¿Es gratis la clave API de Anthropic?

Crear la clave es gratis. Usarla, no. Las preguntas frecuentes de precios de Anthropic dicen que los usuarios nuevos reciben "una pequeña cantidad de créditos gratuitos para probar la API"; después, cada petición se factura por token. Hay una excepción que conviene conocer: en claude.com/pricing, comprobado el 22 de octubre de 2026, el plan Max 5x (100 $/mes) incluye 100 $ al mes y Max 20x 200 $ al mes en créditos de API para Claude Platform; Pro (20 $/mes con facturación mensual) no incluye ninguno. Precios de lista actuales por millón de tokens en la página de precios de Anthropic, 22 de octubre de 2026:

Modelo	ID del modelo	Entrada	Salida	Lectura de caché
Claude Fable 5.1	claude-fable-5-1	$10.00	$50.00	$0.25
Claude Opus 5.5	claude-opus-5-5	$4.00	$20.00	$0.20
Claude Sonnet 5.5	claude-sonnet-5-5	$2.00	$10.00	$0.10
Claude Haiku 5.5 (prompts de hasta 100K)	claude-haiku-5-5	$0.10	$0.50	$0.01

La Batch API reduce a la mitad los precios de entrada y salida, y la inferencia solo en EE. UU. (inference_geo: "us") aplica un multiplicador de 1,1x. Para calcular cargas de trabajo, consulta nuestra guía completa de precios de la API de Anthropic. Si necesitas un modelo realmente gratuito para prototipar, nuestra comparativa de APIs de LLM gratuitas recoge opciones con límites reales.

La clave trae límites de gasto y de velocidad

El nivel de uso de tu organización controla tanto los límites de velocidad como un límite de gasto mensual. Según la página de límites de Anthropic, comprobada el 22 de octubre de 2026, los límites son 500 $ (Start), 1.000 $ (Build) y 200.000 $ (Scale) al mes; las organizaciones nuevas pueden empezar en un nivel Evaluation inferior. Al alcanzar el límite, la API devuelve HTTP 429 hasta las 00:00 UTC del día 1 del mes siguiente, salvo que solicites un nivel superior. También puedes fijar un límite propio más bajo en la página Billing, un buen hábito para cualquier clave que use un agente autónomo.

Errores comunes de la clave API de Anthropic y cómo corregirlos

Error	Causa probable	Solución
401 authentication_error	Clave mal escrita, revocada, desactivada o caducada	Crea una clave nueva; las caducadas no se pueden reactivar
400 invalid_request_error que menciona el workspace	Clave no limitada a un workspace y sin cabecera	Añade anthropic-workspace-id o crea una clave limitada a un workspace
404 not_found_error "Workspace ... not found"	ID de workspace incorrecto o la identidad de la clave no tiene acceso	Comprueba el ID en la página Workspaces
429 "reached your API usage limits"	Se alcanzó el límite de gasto mensual del nivel	Solicita un aumento de nivel o espera al reinicio mensual
429 con retry-after	Se superaron las peticiones o tokens por minuto	Espera y reintenta; ver límites de velocidad de LLM explicados
529 overloaded_error	Capacidad de Anthropic, no tu clave	Reintenta con backoff o haz failover; ver error de API 529
Botón Create key desactivado	Tu rol en Console no puede crear claves	Pide a un administrador un cambio de rol o una clave de cuenta de servicio

Fuentes: documentación de Anthropic de Authentication, límites de velocidad y errores, comprobada el 22 de octubre de 2026.

Mantén la clave segura

• Nunca pegues la clave en código front-end, apps móviles ni notebooks públicos. Para apps de iOS y macOS que deban llamar a Claude directamente, Anthropic ofrece App Attest, que emite tokens de dispositivo que caducan a la hora.
• Usa una clave por entorno y por agente para poder revocar una sin romper las demás.
• Fija una caducidad, aunque sea larga, para que una clave filtrada tenga fecha de expiración.
• Activa el escaneo de secretos en CI; nuestra guía de escaneo de secretos de APIs de IA muestra cómo configurarlo.
• Vigila el uso en Console y define un límite de gasto por debajo del tope de tu nivel.

Cuándo es más sencillo usar una clave para muchos modelos

Una clave de Anthropic solo da acceso a Claude. Si tu producto o tu agente de programación también llama a GPT, Gemini, DeepSeek, Qwen o Kimi, acabas gestionando cinco claves, cinco saldos y cinco conjuntos de límites. Una API unificada como Flatkey emite una sola clave para todos. El 22 de octubre de 2026, las páginas de modelos de Flatkey listaban Claude Sonnet 5.5 a 1,60 $ de entrada / 8,00 $ de salida por millón de tokens y Claude Opus 5.5 a 3,20 $ / 16,00 $, frente a los precios de lista de Anthropic de 2 $ / 10 $ y 4 $ / 20 $. El SDK de Anthropic funciona cambiando la base URL, según la guía del SDK de Anthropic de Flatkey:

import anthropic

client = anthropic.Anthropic(api_key="YOUR_FLATKEY_KEY", base_url="https://router.flatkey.ai")
msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Summarize this changelog in 3 bullets."}],
)
print(next(b.text for b in msg.content if b.type == "text"))

Quédate con una clave directa de Anthropic si necesitas funciones exclusivas de Anthropic el día de su lanzamiento, Workload Identity Federation, controles de residencia de datos o un contrato enterprise. Para una comparación más amplia, lee Flatkey frente a cuentas directas con proveedores y una clave API para varios modelos de IA.

FAQ

¿Cómo obtengo una clave API de Anthropic?

Inicia sesión en Claude Console en platform.claude.com, ve a Settings → API keys, haz clic en Create key, define nombre, caducidad y cuenta vinculada, y copia la clave sk-ant- que se muestra una sola vez. Añade créditos en la página Billing antes de hacer peticiones.

¿Son gratuitas las claves API de Anthropic?

Crear la clave es gratis y las cuentas nuevas reciben un pequeño crédito de prueba, pero después el uso de la API se factura por token. A 22 de octubre de 2026 no existe un nivel gratuito permanente para la API de Claude.

¿Una clave de Claude API es lo mismo que una clave API de Anthropic?

Sí. La documentación de Anthropic indica que las claves de la API de Claude también se llaman claves API de Anthropic. Una clave sirve para todos los modelos Claude a los que tenga acceso tu organización.

¿Dónde encuentro mi clave API de Anthropic existente?

En platform.claude.com/settings/keys puedes ver el nombre, la pista y la caducidad de cada clave, pero no el secreto completo. Si la perdiste, crea una nueva y elimina la antigua.

¿Una suscripción Claude Pro o Max incluye créditos de API?

Pro no. Los planes Max muestran créditos mensuales de API en claude.com/pricing a 22 de octubre de 2026 (100 $/mes en Max 5x y 200 $/mes en Max 20x). Por encima de esos créditos, el uso de la API con una clave de Console se factura por token, aparte de la suscripción de chat.

¿Por qué mi clave API de Anthropic devuelve 401?

La clave está mal escrita, desactivada, eliminada o caducada. Las claves caducadas no se pueden reactivar; crea una nueva. Si el error menciona un workspace, en realidad es un 400 causado por la falta de la cabecera anthropic-workspace-id.

¿Cómo uso mi clave API de Anthropic con Claude Code?

Define ANTHROPIC_API_KEY en tu shell, ejecuta claude y aprueba la clave cuando se te pida. Usa /status dentro de Claude Code para confirmar qué credencial está activa.

Fuentes

• Anthropic: Get your Claude API key, Authentication, Pricing, Rate limits, Models overview, comprobado el 22 de octubre de 2026
• Claude Code: Authentication and IAM, comprobado el 22 de octubre de 2026
• Flatkey: directorio de modelos y guía del SDK de Anthropic, comprobado el 22 de octubre de 2026