Como autenticar Claude API con clave, Bedrock o Vertex
Aprende a autenticar un cliente de Claude en un VPS con clave Anthropic, IAM de AWS, ADC de Google o Microsoft Entra, y a guardar credenciales del servidor.
Las rutas 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. Anthropic incluye la API directa de Claude y cinco plataformas en la nube: Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Google managed), Claude Models on Google Cloud (Anthropic managed) y Microsoft Foundry. La API directa de Anthropic acepta una clave de API o un token de corta duración en una cabecera Authorization: Bearer, y todavía acepta claves de API en la cabecera heredada x-api-key. Amazon Bedrock admite la firma de solicitudes de AWS y claves de API de Bedrock; en esa configuración no existe ninguna clave de Anthropic. 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. Las cuatro secciones siguientes cubren estas configuraciones de credenciales. Las ofertas administradas por Anthropic para AWS y Google Cloud se explican junto con sus plataformas en la nube correspondientes.
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 Bedrock o Vertex. Si el servicio todavía no existe, créelo primero siguiendo crear la primera aplicación de Claude API en un VPS y vuelva aquí para configurar la credencial.
Todo lo que se incluye a continuación se verificó con la documentación de la plataforma de Anthropic en agosto de 2026 y se volvió a comprobar con la documentación de cada proveedor el 16 de octubre de 2026. Los detalles del acceso a modelos de Bedrock se volvieron a comprobar con la documentación de AWS el 19 de octubre de 2026. Las páginas de Anthropic sobre las cuatro rutas, las claves de API y las versiones de API se volvieron a comprobar el 27 de octubre de 2026. Las páginas de Anthropic sobre Microsoft Foundry, los dos endpoints de Bedrock, la ruta administrada por Google, Claude Platform on AWS, la autenticación, Workload Identity Federation y las versiones de API se volvieron a comprobar el 10 de noviembre de 2026, junto con el registro de cambios del SDK de Ruby. Los identificadores de modelo, los precios, las versiones de los SDK y las estructuras de los endpoints cambian con el tiempo. Por eso, esta guía enlaza las páginas de los proveedores en lugar de imprimir 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 peticiones se envían al endpoint Messages del host de la API de Anthropic y cada petición 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 cada petición; los SDK se encargan de establecerla. En octubre de 2026, la documentación de Anthropic presenta Authorization: Bearer como la forma principal de enviar la clave y denomina x-api-key al método antiguo, pero ambos se aceptan, por lo que el comando anterior sigue funcionando. Las versiones principales actuales de los SDK también envían la clave como Authorization: Bearer, por lo que un proxy o gateway que lea X-Api-Key debe modificarse al actualizar. La versión 2023-06-01 del comando todavía se acepta; la versión más reciente de la API de Anthropic es 2026-10-21, que esas versiones de los SDK envían de forma predeterminada y que rechaza algunos parámetros antiguos de las peticiones, como temperature.
La creación del cliente es la más breve de estas configuraciones, 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: opciones predeterminadas de 3 horas, 1 día, 7 días o 30 días, una duración personalizada o Never, según la política de caducidad máxima de su organización. 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 aviso por correo. Una clave caducada devuelve 401 y no se puede reactivar, por lo que la solución siempre es crear una clave nueva.
En la API directa no hay que elegir ninguna región y el coste se factura directamente a su organización de Anthropic. Los espacios de trabajo limitan una clave a un proyecto, que es la forma más clara de saber cuánto gasta un servicio concreto. Limite la clave de un servidor a su espacio de trabajo al crearla: una clave de cuenta personal o de servicio que no esté limitada a un espacio de trabajo debe enviar una cabecera anthropic-workspace-id en cada petición, o la API responde con 400 y invalid_request_error. Para un servicio, elija una clave de cuenta de servicio, porque una clave personal deja de funcionar cuando la persona que la creó abandona la organización. Para consultar el cálculo en el que se basa esa factura, vea 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 de 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 ninguna cadena sk-ant-api.... Es adecuado para Kubernetes, GitHub Actions y las máquinas virtuales en la nube, que ya tienen una identidad de plataforma. Un VPS convencional normalmente no tiene un emisor de ese tipo, por lo que en ese servidor una clave de API almacenada en un archivo es la opción realista; el resto de esta guía parte de esa base.
Ruta 2: Credenciales de AWS en Amazon Bedrock
En Bedrock no necesita ninguna clave de Anthropic. Con las credenciales de AWS, el SDK firma cada petición HTTP con AWS Signature Version 4 (SigV4), y AWS decide si esa identidad puede invocar el modelo.
pip install -U "anthropic[bedrock]"
aws sts get-caller-identityaws sts get-caller-identity muestra el número de cuenta y el ARN (Amazon Resource Name) de la identidad que resuelven sus credenciales. Ejecútelo antes de cualquier otra cosa cuando use SigV4. Para SigV4, el SDK resuelve las credenciales del constructor, las credenciales del entorno y la cadena estándar de credenciales de AWS; la selección de región es independiente. En el cliente de Python AnthropicBedrock, una clave de API de Bedrock proporcionada como api_key o mediante AWS_BEARER_TOKEN_BEDROCK genera ValueError si también pasa aws_access_key, aws_secret_key, aws_session_token o aws_profile. Sin esos argumentos explícitos, la clave selecciona la autenticación bearer en lugar de la cadena de credenciales de AWS. El cliente de TypeScript da prioridad a la clave de API de Bedrock sobre las credenciales de AWS explícitas. El comando de STS no prueba la autenticación bearer.
Lo que cambia en la construcción del cliente es la clase y un argumento.
from anthropic import AnthropicBedrock
client = AnthropicBedrock(aws_region="us-east-1")AnthropicBedrock controla la integración de Bedrock con InvokeModel. A fecha de octubre de 2026, Anthropic también documenta Claude en Amazon Bedrock, con un endpoint de Messages API en https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages para Claude Opus 4.7 y modelos posteriores, al que se accede mediante un cliente AnthropicBedrockMantle del mismo paquete. Admite credenciales de AWS y tokens bearer de Bedrock; los requisitos de acceso al modelo difieren entre ambos endpoints, como se explica más adelante.
Revise la actualización en esa línea pip install -U. A fecha de 27 de octubre de 2026, el SDK más reciente envía por defecto la versión de API 2026-10-21, también a través de Bedrock, y Anthropic documenta que los ID de modelo versionados con ARN que enumera para Claude Opus 4.6 y versiones anteriores no admiten esa versión en Bedrock y pueden devolver un error 400. Si un servicio utiliza uno de esos modelos, mantenga el SDK en la versión que usa actualmente y fíjela, o migre primero el servicio a un modelo Claude 4.7 o posterior.
Aquí la región deja de ser un detalle. Los endpoints de Bedrock son regionales, los modelos Claude disponibles difieren entre regiones y la región forma parte de la firma SigV4, por lo que otra región rechaza una firma calculada para una región distinta. Establezca AWS_REGION explícitamente en el entorno del servicio, porque los SDK no coinciden en el comportamiento cuando se omite. Según la documentación de octubre de 2026, el cliente de Python AnthropicBedrock lee AWS_REGION o AWS_DEFAULT_REGION, después la región de la sesión de boto3 o del perfil de AWS (incluido ~/.aws/config), y genera ValueError si no puede resolver ninguna. El cliente de TypeScript lee AWS_REGION, usa us-east-1 si no está definido y no lee ~/.aws/config para determinar la región. Por eso AWS CLI puede enumerar correctamente los modelos Claude en el mismo equipo donde un proceso de Node usa la región incorrecta: la CLI leyó el archivo de configuración y el cliente no.
En una instancia de EC2 se asocia un rol de IAM (identity and access management) y ningún secreto se almacena en disco, porque el servicio de metadatos de la instancia proporciona credenciales temporales al SDK. Una VPS externa 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 claves de API de Bedrock, que son tokens bearer enviados mediante AWS_BEARER_TOKEN_BEDROCK, y AWS documenta dos tipos. Una clave de corta duración permanece activa hasta 12 horas, o durante la duración de la sesión que la generó si esta es menor, hereda los permisos de la identidad de IAM que la generó y es el tipo que AWS recomienda para producción. Una clave de larga duración permanece activa hasta la fecha de expiración que elija al crearla (por ejemplo, 30 o 90 días con --credential-age-days), o no expira si se omite ese parámetro de API; la consola crea un usuario de IAM asociado y AWS recomienda este tipo sólo para exploración. Una clave de larga duración sólo funciona en la región donde se generó; usarla en otra región devuelve Credential should be scoped to a valid region.
El cargo se registra en su cuenta de AWS y no con Anthropic, que suele ser la razón principal para usar esta opción. Los endpoints regionales tienen una prima del 10% sobre el endpoint global, según la documentación de octubre de 2026. Claude Platform en AWS es un producto independiente: Anthropic lo opera, AWS lo factura mediante AWS Marketplace y se autentica con SigV4 o con una clave de API generada en la consola de AWS (las claves de la consola de Claude no funcionan allí), mediante un cliente AnthropicAWS que Anthropic marca como beta. Conviene reconocer un error de Bedrock 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 corresponde al enrutamiento del modelo y ningún cambio de credenciales lo solucionará.
Ruta 3: credenciales de Google en Vertex AI
La documentación de Anthropic denomina ahora esta ruta Claude Models on Google Cloud (gestionado por Google), que Google ejecuta como parte de su Agent Platform, el nuevo nombre de Google para lo que surgió de Vertex AI. El host aiplatform.googleapis.com, el extra anthropic[vertex] y la clase AnthropicVertex que se muestran a continuación no cambian.
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 especificarla. 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 loginEn una estación de trabajo, ese inicio de sesión escribe $HOME/.config/gcloud/application_default_credentials.json y el proceso termina. En un servidor, evite almacenar las credenciales de un usuario; el comando también admite la suplantación de una cuenta de servicio. Fuera de Google Cloud tampoco existe un servidor de metadatos de Google, por lo que debe usar GOOGLE_APPLICATION_CREDENTIALS para indicar a ADC un archivo de configuración de Workload Identity Federation o un archivo de clave de cuenta de servicio. Un archivo JSON de clave de cuenta de servicio es un secreto de larga duración y requiere exactamente el tratamiento descrito 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. La identidad que encuentre ADC necesita un rol de IAM que incluya el permiso aiplatform.endpoints.predict, como Agent Platform User (roles/aiplatform.user).
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")Hay dos cambios si desciende del SDK al HTTP sin procesar. El identificador del modelo sale del cuerpo de la solicitud y pasa a la ruta URL, mientras que anthropic_version sale de la cabecera y pasa al cuerpo. A fecha de 27 October 2026, la documentación de Anthropic acepta allí vertex-2023-10-16 o la versión de API más reciente 2026-10-21. La credencial es un token de acceso normal de Google. En el comando siguiente, gcloud auth print-access-token usa el inicio de sesión propio de la CLI de gcloud en lugar de ADC, por lo que debe ejecutar primero gcloud auth login o gcloud init en la máquina donde lo pruebe.
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 principal. global realiza el encaminamiento dinámico según la disponibilidad, us y eu son identificadores multirregión, y un nombre como us-east5 fija una sola región. A fecha de October 2026, Anthropic documenta endpoints de una sola región únicamente para Claude Sonnet 4.6 y versiones anteriores; los modelos más recientes usan los endpoints globales o multirregión. Los endpoints multirregión y regionales cuestan un 10% más que los globales, según la documentación de October 2026. La facturación se realiza mediante el proyecto de Google Cloud, por lo que las cuotas y las facturas son de Google.
A fecha de 27 October 2026, Anthropic también documenta una segunda oferta de Google Cloud, cuya estructura de solicitud es diferente. En Claude Models on Google Cloud (gestionado por Anthropic), Anthropic opera directamente la API de Claude en claude.googleapis.com, a la que se accede mediante un cliente AnthropicGoogleCloud. Sigue autenticándose con credenciales de Google Cloud, incluido ADC, pero la solicitud se parece a la de la API directa: model permanece en el cuerpo y la versión se envía en la cabecera anthropic-version. El acceso procede de sus propios roles de IAM (roles/claude.user y otros relacionados), la configuración crea una organización nueva de Anthropic para el proyecto y el uso se factura mediante Google Cloud Marketplace. Si las URL de sus solicitudes contienen aiplatform y terminan en :rawPredict, está usando la ruta gestionada por Google que se describe en esta sección.
Ruta 4: Microsoft Foundry es la ruta de Azure
Si buscó Claude en Azure, esta es la sección que necesita. Existe una ruta compatible. Claude se ejecuta en Microsoft Foundry (antes Azure AI Foundry) y se factura mediante Azure Marketplace en Claude Consumption Units. Cree un recurso de Foundry, implemente un modelo de Claude dentro de él y llame a un endpoint alojado en Azure en https://{resource}.services.ai.azure.com/anthropic/v1/*.
Hay dos credenciales disponibles. La primera es una clave emitida por Azure desde la pestaña Details de la implementación en el portal de Foundry. Se envía en una cabecera api-key o x-api-key. La segunda es un token de Microsoft Entra. Es la opción preferible 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 se asigna un nombre personalizado a la implementación. Esta es la causa habitual de un error Deployment not found en una solicitud que, por lo demás, es correcta. Los SDK de Python y TypeScript leen ANTHROPIC_FOUNDRY_API_KEY y ANTHROPIC_FOUNDRY_RESOURCE del entorno. Según la documentación del 10 de noviembre de 2026, Foundry es compatible con los siete SDK oficiales: C#, Go, Java, PHP, Python, Ruby y TypeScript. Go usa un paquete específico foundry (go get github.com/anthropics/anthropic-sdk-go/v2/foundry), y Ruby incorporó un Anthropic::FoundryClient específico en la versión 2.5.0 de la gema, publicada el 4 de noviembre de 2026. Antes de esa versión, el código de Ruby tenía que apuntar el cliente genérico a la URL base de Foundry.
Apuntar un cliente genérico a la URL base de Foundry todavía presenta un riesgo, tanto si se trata de código Ruby escrito antes de la versión 2.5.0 como de la CLI ant, que los propios ejemplos de Foundry de Anthropic utilizan de esa forma. Si no pasa las credenciales explícitamente al cliente genérico y ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN sigue definida en el entorno, el cliente la toma y envía su credencial de Anthropic a un endpoint de Microsoft. Anule la variable o pase explícitamente la clave o el token de Foundry al cliente. En Ruby, migrar a Anthropic::FoundryClient, que acepta la clave de Foundry o un proveedor de tokens de Entra, es la solución más limpia. Un token de acceso de Entra tiene una duración predeterminada aleatoria de 60 a 90 minutos. Por tanto, un proceso de larga duración debe renovarlo y no conservar un único token desde el inicio.
¿Cuánto tiempo permanece válido el credencial de su servidor?
Los datos de este gráfico
[
{
"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 short-term API key",
"max_lifetime_hours": 12
},
{
"label": "Entra ID access token, default upper bound",
"max_lifetime_hours": 1.5
},
{
"label": "Federated Anthropic token, default",
"max_lifetime_hours": 1
}
]Estos son los límites máximos y valores predeterminados publicados por cada proveedor y consultados en octubre de 2026, no cifras medidas. Importan por una razón: indican cuánto tiempo sigue funcionando un credencial filtrado mientras usted aún está descubriendo que se ha filtrado. El token federado de Anthropic, situado al final del gráfico, dura hasta 1 horas de forma predeterminada y también está limitado por el doble de la vida útil restante del token del proveedor de identidad. Un token de acceso de Microsoft Entra no tiene un valor predeterminado único: Microsoft asigna a cada uno una duración aleatoria de entre 60 y 90 minutos, con una media de 75, que se muestra en el gráfico en su límite superior de 1.5 horas. Ese valor predeterminado también varía según el cliente, el recurso y si Conditional Access está habilitado en el tenant. Cuando tanto el cliente como el recurso admiten Continuous Access Evaluation, Entra puede ampliar la duración a entre 24 y 28 horas y revocar el token casi en tiempo real ante eventos como la deshabilitación de la cuenta. Una política de duración de tokens del tenant puede establecerla entre 10 minutos y 23:59:59. Los SDK actualizan automáticamente los tokens federados de Anthropic. En Foundry, configure un proveedor de tokens de Entra para actualizar los tokens en lugar de pasar una cadena de token fija. Una regla de federación puede establecer su propia duración de token entre un minuto y 24 horas. El asistente Connect workload de Console establece inicialmente 10 minutos, por lo que debe leer la regla y no asumir el valor predeterminado. Un rol asumido y una clave de API de corta duración de Bedrock tienen una duración de 12 horas. Una clave de API de larga duración de Bedrock no aparece en el gráfico porque no tiene un límite máximo fijo: permanece válida hasta la fecha de caducidad elegida al crearla o no caduca si se omitió CredentialAgeDays en la llamada a la API. Por eso AWS recomienda usarla sólo para exploración. Una clave creada con el valor preestablecido de 30 días sigue siendo válida durante 720 horas. Es el 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 la versión del SDK, así 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/envEl archivo contiene líneas KEY=value simples. No use 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.targetsystemd lee EnvironmentFile= como root, antes de cambiar a User=claudeapp, por lo que la cuenta de servicio nunca necesita acceso de lectura al archivo. El modo 600 y el propietario root son suficientes. Por eso el comando install anterior lo configura así. Inícielo con sudo systemctl enable --now claude-app y confirme con systemctl status claude-app que la unidad ha alcanzado active (running) en lugar de reiniciarse en un bucle.
Hay cuatro cosas que debe evitar. Cada una tiene un motivo que puede comprobar por sí mismo:
- No escriba la clave con
Environment=dentro del archivo de unidad. Una unidad en/etc/systemd/systempuede leerla cualquier usuario, por lo quesystemctl cat claude-appmuestra el secreto a cualquier usuario local. - No haga commit del secreto.
.gitignoreexcluye un archivo nuevo de un commit, pero no hace nada con un archivo que ya se haya incluido en un commit, porque el historial de git conserva todo lo que recibió. - No lo incluya en una imagen de contenedor. Los valores de
ENVpermanecen en la configuración de la imagen, y los argumentos de compilación son visibles en el historial de la imagen o en los metadatos de procedencia. Eliminar el archivo en una capa posterior no lo elimina de la capa anterior. Pase los secretos en tiempo de ejecución con--env-fileo mediante un archivo montado. - No considere privado para root el entorno del proceso.
sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n'vuelve a mostrar la clave. El comando que lee el archivo necesitasudo; una redirección de entrada del shell se ejecuta antes desudoy usa los permisos de la cuenta actual. El objetivo es mantener el secreto alejado de todas las demás cuentas del sistema, no de root, que puede leerlo haga lo que haga.
Este último punto delimita lo que ofrece este diseño. El archivo accesible sólo por root protege la clave almacenada, pero cualquier código que se ejecute con la cuenta de servicio puede leer el entorno del proceso, y los procesos secundarios lo heredan. Es el contenedor incorrecto cuando el proceso ejecuta código que usted no ha escrito, porque cualquier cosa que el proceso pueda ejecutar puede leer su propio entorno. Mantener los secretos fuera del alcance de un agente de IA cubre ese caso, que es un problema distinto con una solución distinta.
¿Cómo roto la clave sin tiempo de inactividad?
Rote primero la clave nueva y revoque la anterior al final. El reinicio del servicio único que se muestra a continuación interrumpe brevemente el servicio; para mantener la disponibilidad, otra instancia debe atender las peticiones durante el reinicio.
- Cree la clave nueva en la Console, en el mismo workspace que la anterior.
- Escríbala en
/etc/claude-app/envconsudoedit. - Ejecute
sudo systemctl restart claude-app. - Confirme que el servicio responde a las peticiones y, después, revoque 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 arrancar. systemctl daemon-reload vuelve a leer los archivos de unidad y no modifica el entorno de un proceso en ejecución, de modo que sólo un reinicio aplica la clave nueva. Revocar la clave en el paso 1 en lugar del paso 4 provoca una interrupción que dura hasta el paso 3.
Las rutas de cloud se rotan en el proveedor. Un usuario de IAM admite dos claves de acceso activas a la vez: cree la segunda, impleméntela y después elimine la primera. Una clave de cuenta de servicio de Google se rota del mismo modo. Un recurso de Foundry contiene dos claves, y regenerar una hace que su valor anterior deje de funcionar de inmediato. Por tanto, cambie el servicio a la otra clave antes de regenerar la que estaba utilizando. Los tokens de Entra y los tokens federados de Anthropic no requieren una rotación manual, lo que constituye 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 cara antes que cualquier otra cosa, y limitar lo que puede gastar un agente en un VPS 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 suele pasar desapercibida 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. Una clave personal también deja de funcionar cuando su propietario abandona la organización.
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 ellos la oculta. El caso más problemático es este: una variable exportada como cadena vacía sigue ocupando su posición, así que ANTHROPIC_API_KEY="" hace que el SDK se autentique con una clave vacía en lugar de continuar con el siguiente método. Use unset ANTHROPIC_API_KEY.
401 con el mensaje aislado Authentication failed en la federación. Ese mensaje es deliberadamente idéntico para todas las causas posibles, de modo que un cliente no pueda deducir la configuración de las reglas leyendo el 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 intentar adivinar el problema del JWT.
403 en Foundry. El token se autenticó correctamente, 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. Para la autenticación SigV4, ejecute primero aws sts get-caller-identity como el usuario del servicio. El comando indica si el sistema 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. A fecha del 29 October 2026, AWS habilita el acceso a muchos modelos durante el primer uso en regiones comerciales con los permisos necesarios de AWS Marketplace, pero algunos modelos requieren acceso independiente a nivel de cuenta. Los modelos de Anthropic invocados mediante la ruta InvokeModel requieren primero un formulario de caso de uso por cuenta (o uno para toda una AWS Organization, aunque las regiones de activación voluntaria lo requieren de nuevo) y, hasta que se aprueba, la llamada devuelve AccessDeniedException. AWS documenta que el formulario no se aplica al endpoint bedrock-mantle. La primera llamada a un modelo en una cuenta también hace que Bedrock inicie en segundo plano la suscripción de AWS Marketplace. Esa suscripción necesita una identidad con los permisos aws-marketplace:Subscribe, aws-marketplace:Unsubscribe y aws-marketplace:ViewSubscriptions. La falta de permisos no necesariamente hace fallar la primera llamada: AWS documenta que las llamadas pueden funcionar durante un máximo de 15 minutos mientras se configura la suscripción. Cuando la suscripción falla, las llamadas posteriores devuelven el mismo AccessDeniedException. Un servicio que funcionó durante sus primeros minutos y después empezó a fallar apunta a este problema, no a sus credenciales. Después de conceder los permisos, AWS permite hasta 2 minutos para completar la suscripción. Un modelo que no se ofrece en la región utilizada falla independientemente de que las credenciales sean válidas.
FAQ
¿Necesito una clave de API de Anthropic para usar Claude en Bedrock o Vertex?
No. En Amazon Bedrock, el SDK firma las solicitudes con credenciales de AWS mediante SigV4 o envía una clave de API de Bedrock, y en Google Cloud envía un token de acceso de Google obtenido mediante Application Default Credentials. En ninguna de las dos configuraciones existe un secreto emitido por Anthropic, y el uso se factura a la cuenta cloud, no a Anthropic. Por eso también es peligroso dejar una clave de Anthropic en ANTHROPIC_API_KEY en esos hosts: un cliente genérico dirigido a un endpoint 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 a través de Azure Marketplace en Claude Consumption Units. El campo model del cuerpo de la solicitud debe contener el nombre de su deployment, que sólo coincide con el identificador del modelo si mantuvo el nombre predeterminado al crear el deployment; el nombre no se puede cambiar después.
¿Dónde debo almacenar la clave de API de Claude en un servidor Linux?
En un archivo propiedad de root con modo 600, cargado mediante EnvironmentFile= en una unidad de systemd. systemd lee ese archivo como root antes de cambiar al User= de la unidad, por lo que la cuenta del servicio no necesita acceso a él. Manténgalo fuera del repositorio, fuera del propio archivo de la unidad (que es legible por todos y se muestra mediante systemctl cat) y fuera de la configuración de la imagen del contenedor, sus capas y los metadatos de compilación.
¿Por qué mi solicitud a la API de Claude empezó a devolver 401 si nada cambió?
Una clave que alcanza la fecha de caducidad establecida al crearla devuelve 401. La caducidad se establece durante la creación, no se puede editar después y las claves de corta duración caducan sin enviar un correo de advertencia. Una clave caducada no se puede reactivar. Cree una clave de reemplazo, escríbala en el archivo de entorno, reinicie el servicio y revoque la clave antigua después. Si la clave está vigente, compruebe que una credencial obsoleta no la esté ocultando: ANTHROPIC_API_KEY establecido en una cadena vacía sigue teniendo prioridad sobre las fuentes de federación y de perfil que aparecen después.