Autenticación de Claude API: clave, Bedrock y Vertex

Las cuatro vías de autenticación de Claude API

La autenticación de Claude API se reduce a una decisión: qué credencial envía el cliente por la red. Hay cuatro opciones y no son variantes de un mismo mecanismo. La API directa de Anthropic envía una clave estática en una cabecera x-api-key. Amazon Bedrock firma cada petición con credenciales de AWS y no existe ninguna clave de Anthropic en esa configuración. Google Cloud envía un token de acceso de Google de corta duración. Microsoft Foundry usa una clave emitida por Azure o un token de Microsoft Entra.

Esta guía explica cómo integrar un SDK (kit de desarrollo de software) en un servicio que se ejecuta en un servidor Linux. Si está configurando la herramienta de línea de comandos Claude Code, las variables y el flujo son diferentes: consulte configurar Claude Code para usar Bedrock o Vertex. Si el servicio todavía no existe, créelo primero con crear una primera aplicación de Claude API en un VPS y vuelva aquí para configurar la credencial.

Todo lo siguiente se verificó con la documentación de la plataforma de Anthropic en agosto de 2026. Los identificadores de modelo, los precios, las versiones de los SDK y las estructuras de los endpoints cambian con frecuencia. Por eso, esta guía enlaza las páginas de los proveedores en lugar de incluir valores que quedan obsoletos.

Ruta 1: una clave de API de Anthropic

Esta es la ruta directa y la única en la que Anthropic emite el secreto. Las solicitudes se envían al endpoint Messages del host de la API de Anthropic y cada solicitud incluye tres cabeceras.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "MODEL_ID", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

Sustituya MODEL_ID por un identificador actual de la descripción general de modelos de Anthropic. Una respuesta correcta es un JSON que contiene un array content y un objeto usage. Una clave incorrecta o caducada devuelve HTTP 401 con authentication_error. La ausencia de la cabecera anthropic-version provoca un fallo distinto, porque esa cabecera es obligatoria en todas las solicitudes; los SDK la establecen automáticamente.

La creación del cliente es la más sencilla de las cuatro, porque no hay nada que construir. Todos los SDK oficiales leen ANTHROPIC_API_KEY del entorno por su cuenta.

import os
from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

message = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=64,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.usage)

Conviene mantener el identificador del modelo en el entorno junto a la clave. Los nombres de los modelos cambian según un calendario que usted no controla, y volver a desplegar el código para editar una cadena es trabajo evitable.

Las claves se crean en la Console, donde se elige su caducidad en el momento de crearlas: valores predefinidos de 3 horas, 1 día, 7 días o 30 días, una duración personalizada o Never. La caducidad se fija al crear la clave y no se puede cambiar después. Anthropic envía un correo electrónico al creador de la clave antes de que caduque una clave de larga duración, pero una clave con una duración corta caduca sin ningún correo de advertencia. Una clave caducada devuelve 401 y no se puede reactivar, por lo que la solución siempre es crear una clave nueva.

No hay ninguna región que elegir en la API directa y el coste se factura directamente a su organización de Anthropic. Los Workspaces limitan una clave a un proyecto, que es la forma más clara de saber cuánto gasta un servicio concreto. Para consultar el cálculo en el que se basa esa factura, consulte cómo se compara el precio de la API por token con una suscripción.

Hay otra opción que corresponde mencionar aquí, porque elimina por completo el secreto estático. Workload Identity Federation permite que una carga de trabajo intercambie un token OpenID Connect (OIDC) de un proveedor de identidad en el que ya confía por un token de Anthropic de corta duración en POST /v1/oauth/token, y el SDK renueva ese token antes de que caduque. Nunca se genera ni se copia en ningún sitio una cadena sk-ant-api.... Esta opción encaja con Kubernetes, GitHub Actions y las máquinas virtuales en la nube, que ya tienen una identidad de plataforma. Un VPS normal normalmente no tiene un emisor de este tipo, por lo que en ese equipo la respuesta adecuada es una clave de API en un archivo, y el resto de esta guía lo trata de esa forma.

Ruta 2: credenciales de AWS en Amazon Bedrock

En Bedrock no se usa ninguna clave de Anthropic. El SDK firma cada petición HTTP con AWS Signature Version 4 (SigV4) mediante credenciales de AWS normales, y AWS decide si esa identidad puede invocar el modelo.

pip install -U "anthropic[bedrock]"
aws sts get-caller-identity

aws sts get-caller-identity muestra el número de cuenta y el ARN (Amazon Resource Name) de la identidad que resuelven las credenciales. Ejecútelo antes de cualquier otra cosa. Si falla, la llamada a Claude también fallará, porque el SDK recorre la misma cadena: primero los argumentos del constructor, después AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN y AWS_REGION, y luego el archivo de configuración de AWS y el resto de la cadena estándar (SSO, roles asumidos, el rol de tarea de ECS y el servicio de metadatos de instancia).

En la construcción del cliente sólo cambian la clase y un argumento.

from anthropic import AnthropicBedrock

client = AnthropicBedrock(aws_region="us-east-1")

Aquí la región no es un dato decorativo. Los endpoints de Bedrock son específicos de cada región, el acceso a los modelos se concede por región en la consola de AWS y la región forma parte de la firma SigV4. Por tanto, otra región rechazará una firma calculada para una región distinta. Defina AWS_REGION explícitamente en el entorno del servicio. Anthropic documenta que el cliente AnthropicBedrock lee AWS_REGION y usa us-east-1 como alternativa cuando no está definido, y que no lee ~/.aws/config para determinar la región. Por eso AWS CLI puede enumerar correctamente los modelos de Claude en el mismo equipo en el que falla el proceso de Python: AWS CLI leyó el archivo de configuración y el cliente no.

En una instancia EC2 se asocia un rol de IAM (identity and access management) y ningún secreto se guarda en disco, porque el servicio de metadatos de instancia entrega credenciales temporales al SDK. Un VPS externo a AWS no tiene ni un rol de instancia ni un servicio de metadatos. En ese caso debe elegir entre un par de claves de acceso de larga duración de un usuario de IAM almacenado en el equipo, que pertenece a la misma clase de secretos que una clave de Anthropic, y la federación: autenticarse con el proveedor de identidad, llamar a AWS STS (security token service) y usar las credenciales temporales que devuelve. Bedrock también acepta un token bearer mediante AWS_BEARER_TOKEN_BEDROCK. La documentación establece un límite de 12 horas y AWS describe esta opción como la menos preferida.

El cargo se factura en su cuenta de AWS y no a Anthropic. Normalmente, esa es precisamente la razón para elegir esta opción. Los endpoints regionales tienen un recargo del 10% respecto al endpoint global, según la documentación disponible en agosto de 2026. Hay un error de Bedrock que conviene reconocer porque parece un problema de permisos, pero no lo es: Invocation of model ID ... with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model. Ese error indica un problema de enrutamiento del modelo. Cambiar las credenciales no lo solucionará.

Ruta 3: Credenciales de Google en Vertex AI

Google Cloud usa Application Default Credentials (ADC), un orden de búsqueda fijo que siguen las bibliotecas de autenticación de Google para encontrar una credencial sin que tenga que indicar una. ADC comprueba primero GOOGLE_APPLICATION_CREDENTIALS, después el archivo escrito por gcloud auth application-default login y, por último, la cuenta de servicio asociada mediante el servidor de metadatos.

pip install -U "anthropic[vertex]"
gcloud auth application-default login

En una estación de trabajo, ese inicio de sesión escribe $HOME/.config/gcloud/application_default_credentials.json y el proceso termina ahí. En un servidor, es la herramienta incorrecta porque la credencial que almacena pertenece a una persona y deja de funcionar cuando se elimina su cuenta. Fuera de Google Cloud tampoco existe un servidor de metadatos, por lo que ADC termina usando GOOGLE_APPLICATION_CREDENTIALS, que apunta a un archivo de clave de una cuenta de servicio. Ese archivo JSON es un secreto de larga duración y debe manejarse exactamente como se describe más adelante en esta guía. Dentro de Google Cloud, asocie una cuenta de servicio a la VM y no habrá ningún archivo que proteger.

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="my-project", region="global")

Hay dos cambios al usar HTTP sin pasar por el SDK. El identificador del modelo sale del cuerpo de la petición y pasa a la ruta de la URL, mientras que anthropic_version sale de la cabecera y pasa al cuerpo, donde debe aparecer como vertex-2023-10-16. La credencial es un token de acceso de Google normal.

curl https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/anthropic/models/${MODEL_ID}:rawPredict \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

La región es un argumento de primer nivel. global realiza el enrutamiento dinámico según la disponibilidad, us y eu son identificadores multirregión, y un nombre como us-east5 fija una sola región. Los endpoints multirregión y regionales cuestan un 10% más que el endpoint global, según la documentación de agosto de 2026. La facturación se realiza mediante el proyecto de Google Cloud, por lo que las cuotas y las facturas corresponden a Google.

Ruta 4: Microsoft Foundry es la opción de Azure

Si buscó Claude en Azure, esta es la sección que necesitaba y existe una opción compatible. Claude se ejecuta en Microsoft Foundry (antes Azure AI Foundry) y se factura mediante Azure Marketplace en Claude Consumption Units. Debe crear un recurso de Foundry, implementar un modelo de Claude en él y llamar a un endpoint alojado en Azure en https://{resource}.services.ai.azure.com/anthropic/v1/*.

Se pueden usar dos credenciales. La primera es una clave emitida por Azure, disponible en la pestaña Details de la implementación en el portal de Foundry. Debe enviarse en una cabecera api-key o x-api-key. La segunda es un token de Microsoft Entra. Es la mejor opción en un servidor porque el control de acceso basado en roles de Azure determina quién puede llamar al endpoint.

ACCESS_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl https://${RESOURCE}.services.ai.azure.com/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "DEPLOYMENT_NAME", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

El campo model contiene el nombre de la implementación, no un identificador de modelo. De forma predeterminada, ambos valores coinciden. Dejan de coincidir en cuanto asigna un nombre propio a la implementación. Esta es la causa habitual de un error Deployment not found en una petición que, por lo demás, es correcta. Los SDK de Python y TypeScript leen ANTHROPIC_FOUNDRY_API_KEY y ANTHROPIC_FOUNDRY_RESOURCE del entorno. Foundry no es compatible con todos los SDK: según la documentación disponible en agosto de 2026, es compatible con C#, Java, PHP, Python y TypeScript. Los SDK de Go y Ruby necesitan usar el cliente genérico apuntando a la URL base de Foundry.

Esta solución alternativa tiene un riesgo concreto. Si ANTHROPIC_API_KEY todavía está definido en el entorno, el cliente genérico lo recoge y envía su clave de Anthropic a un endpoint de Microsoft. Anule la variable o desactive los valores predeterminados del entorno en el cliente. Los tokens de Entra caducan aproximadamente al cabo de una hora. Por tanto, un proceso de larga duración debe renovarlos en lugar de capturar uno al iniciarse.

¿Cuánto tiempo permanece válida la credencial de su servidor?

[
  {
    "label": "Anthropic key, 30-day preset",
    "max_lifetime_hours": 720
  },
  {
    "label": "Anthropic key, 7-day preset",
    "max_lifetime_hours": 168
  },
  {
    "label": "AWS STS assumed role",
    "max_lifetime_hours": 12
  },
  {
    "label": "Bedrock bearer token",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token",
    "max_lifetime_hours": 1
  },
  {
    "label": "Federated Anthropic token",
    "max_lifetime_hours": 1
  }
]

Estos son los límites máximos y valores predeterminados publicados por cada proveedor y consultados en agosto de 2026, no cifras medidas. Importan por una razón: indican cuánto tiempo seguirá funcionando una credencial filtrada mientras usted aún determina que se ha filtrado. Los tokens de corta duración de la parte inferior del gráfico permanecen válidos 1 hora cada uno. El SDK los renueva, por lo que su corta duración no añade ningún coste operativo. Un rol asumido tiene una duración de 12 horas. Una clave creada con el ajuste preestablecido de 30 días sigue siendo válida durante 720 horas. Es la credencial que permanece en un archivo del servidor durante un mes.

Dónde reside la credencial en un VPS

Guarde el secreto en un archivo que sólo root pueda leer y deje que systemd se lo entregue al proceso. Esta parte no depende de ninguna versión del SDK, por lo que conviene configurarla una vez y correctamente.

sudo useradd --system --home /opt/claude-app --shell /usr/sbin/nologin claudeapp
sudo install -d -m 700 -o root -g root /etc/claude-app
sudo install -m 600 -o root -g root /dev/null /etc/claude-app/env
sudoedit /etc/claude-app/env

El archivo contiene líneas simples de KEY=value. No incluya export, comillas ni sintaxis de shell, porque systemd lo analiza directamente en lugar de ejecutarlo mediante un shell.

ANTHROPIC_API_KEY=sk-ant-api03-REPLACE-ME
CLAUDE_MODEL=REPLACE-ME

[Unit]
Description=Claude API service
After=network-online.target

[Service]
User=claudeapp
EnvironmentFile=/etc/claude-app/env
ExecStart=/opt/claude-app/venv/bin/python -m claude_app
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemd lee EnvironmentFile= como root, antes de cambiar a User=claudeapp, por lo que la cuenta del servicio nunca necesita permisos de lectura sobre el archivo. Es suficiente que el archivo pertenezca a root y tenga permisos 600. Por eso el comando install anterior lo configura de esa forma. Inícielo con sudo systemctl enable --now claude-app y confirme con systemctl status claude-app que la unidad haya alcanzado active (running) en lugar de reiniciarse en un bucle.

Evite estas cuatro cosas. Cada una tiene un motivo que puede comprobar:

• No escriba la clave con Environment= dentro del archivo de unidad. Una unidad situada en /etc/systemd/system es legible por todos los usuarios, por lo que systemctl cat claude-app muestra el secreto a cualquier usuario local.
• No haga commit del archivo. .gitignore excluye un archivo nuevo de un commit, pero no hace nada con un archivo que ya se haya incluido, porque el historial de Git conserva todo lo que se le haya entregado.
• No incluya el secreto en una imagen de contenedor. Las líneas ENV y los valores --build-arg quedan registrados en las capas de la imagen, y docker history --no-trunc los muestra. Eliminar el archivo en una capa posterior no lo elimina de la capa anterior. En su lugar, proporcione los secretos en tiempo de ejecución con --env-file o mediante un archivo montado.
• No considere privado para root el entorno del proceso. sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ muestra la clave. El objetivo es mantener el secreto alejado de todas las demás cuentas del servidor, no de root, que puede leerlo independientemente de lo que haga.

Este último punto define el límite de lo que ofrece este diseño. Una variable de entorno es un contenedor adecuado para un secreto cuando las únicas entidades que pueden leerla son el servicio y root. Es un contenedor inadecuado cuando el proceso ejecuta código que usted no ha escrito, porque cualquier código que el proceso pueda ejecutar puede leer su propio entorno. Mantener los secretos fuera del alcance de un agente de IA trata ese caso. Es un problema distinto y requiere una solución diferente.

¿Cómo roto la clave sin tiempo de inactividad?

Rote primero la nueva clave y revoque la anterior después.

1. Cree la nueva clave en la Console, en el mismo workspace que la anterior.
2. Escríbala en /etc/claude-app/env con sudoedit.
3. Ejecute sudo systemctl restart claude-app.
4. Confirme que el servicio responde a las solicitudes y revoque después la clave anterior en la Console.

EnvironmentFile se lee cuando se inicia la unidad, por lo que un proceso en ejecución conserva el valor que recibió al iniciarse. systemctl daemon-reload vuelve a leer los archivos de unidad, pero no modifica el entorno de un proceso en ejecución. Por tanto, sólo un reinicio carga la nueva clave. Si revoca la clave en el paso 1 en lugar del paso 4, provocará una interrupción que durará hasta el paso 3.

Las otras tres opciones rotan la clave en el proveedor. Un usuario de IAM admite dos claves de acceso activas al mismo tiempo. Cree la segunda, impleméntela y elimine después la primera. Una clave de una cuenta de servicio de Google se rota de la misma forma. Una clave de Foundry se regenera en el portal, lo que invalida inmediatamente la anterior. Por tanto, escriba el nuevo valor antes de hacer clic. Los tokens de Entra y los tokens federados de Anthropic no necesitan rotación. Este es el argumento más sólido para usarlos cuando sea posible.

Mientras está en la Console, establezca un límite de gasto para el workspace. Una clave filtrada resulta costosa antes que cualquier otra cosa, y limitar lo que un agente en un VPS puede gastar explica los controles disponibles.

¿Por qué mi cliente devuelve 401 o 403?

401 con authentication_error en la API directa. La clave es incorrecta, se revocó o superó su fecha de caducidad. La caducidad es lo que más se pasa por alto, porque el código no cambió y la solicitud funcionaba ayer. Compruebe la columna de caducidad de la clave en la Console o lea expires_at desde la Admin API, donde aparece como null para las claves sin caducidad.

El SDK ignora la configuración de federación y usa una clave. ANTHROPIC_API_KEY y ANTHROPIC_AUTH_TOKEN tienen prioridad sobre la federación en el orden de precedencia de credenciales, por lo que cualquiera de los dos la oculta. El caso más difícil de detectar es este: una variable exportada como cadena vacía sigue ocupando su posición, por lo que ANTHROPIC_API_KEY="" hace que el SDK se autentique con una clave vacía en lugar de continuar con la siguiente opción. Use unset ANTHROPIC_API_KEY.

401 con el mensaje sin más Authentication failed en la federación. El mensaje es deliberadamente idéntico para todas las causas posibles, de modo que un cliente no pueda deducir la configuración de las reglas a partir del texto del error. El motivo real se registra en la página del historial de autenticación de la Console. Empiece por ahí en lugar de hacer suposiciones sobre el JWT.

403 en Foundry. El token se autenticó, pero su cuenta de Azure no tiene un rol que permita realizar la llamada. Asigne un rol de Azure RBAC, como Foundry User (antes Azure AI User) o Cognitive Services User, a la identidad que realiza la solicitud.

Cualquier error en Bedrock. Ejecute aws sts get-caller-identity primero como el usuario del servicio. El comando indica si el equipo tiene credenciales de AWS utilizables, lo que permite distinguir un problema de credenciales de un problema de acceso al modelo o de una región incorrecta. El acceso al modelo se concede por región en la consola de AWS. Es fácil habilitarlo en una región y realizar la llamada en otra.

FAQ

¿Necesito una clave de API de Anthropic para usar Claude en Bedrock o Vertex?

No. En Amazon Bedrock, el SDK firma cada solicitud con credenciales de AWS mediante SigV4. En Google Cloud, envía un token de acceso de Google obtenido mediante Application Default Credentials. Ninguna de las dos configuraciones usa un secreto emitido por Anthropic. El uso se factura a la cuenta de cloud correspondiente, no a Anthropic. Por eso una clave de Anthropic almacenada en ANTHROPIC_API_KEY supone un riesgo en esos hosts: un cliente genérico dirigido a un endpoint de cloud la enviará allí sin problemas.

¿Está disponible Claude en Azure?

Sí, mediante Microsoft Foundry, antes llamado Azure AI Foundry. Debe crear un recurso de Foundry, desplegar un modelo de Claude en él y llamar a https://{resource}.services.ai.azure.com/anthropic/v1/messages con una clave emitida por Azure en una cabecera api-key o con un token bearer de Microsoft Entra. El uso se factura mediante Azure Marketplace en Claude Consumption Units. El campo model del cuerpo de la solicitud debe contener el nombre de su despliegue. Sólo coincide con el identificador del modelo hasta que cambia el nombre del despliegue.

¿Dónde debo almacenar la clave de API de Claude en un servidor Linux?

En un archivo propiedad de root con permisos 600, cargado mediante EnvironmentFile= en una unidad de systemd. systemd lee ese archivo como root antes de cambiar a User= de la unidad, por lo que la cuenta de servicio no necesita acceso a él. Manténgalo fuera del repositorio y del archivo de unidad, que puede leerse públicamente y cuyo contenido muestra systemctl cat. También debe mantenerlo fuera de las capas de la imagen del contenedor, ya que docker history --no-trunc muestra cualquier valor definido con ENV o --build-arg.

¿Por qué mi solicitud a la API de Claude empezó a devolver 401 si no cambió nada?

La causa más habitual es que la clave haya alcanzado la fecha de caducidad elegida al crearla. La caducidad se establece durante la creación y no puede modificarse después. Las claves de corta duración caducan sin enviar un correo de advertencia. Una clave caducada no puede reactivarse. Cree una clave de reemplazo, escríbala en el archivo de entorno, reinicie el servicio y revoque después la clave antigua. Si la clave sigue vigente, compruebe que una credencial obsoleta no la esté ocultando: ANTHROPIC_API_KEY establecido en una cadena vacía mantiene precedencia sobre cualquier otra fuente de credenciales.