Authentifier l’API Claude : clé, Bedrock, Vertex, Foundry

Les quatre méthodes d’authentification de l’API Claude

L’authentification de l’API Claude repose sur une seule décision : quel identifiant votre client transmet sur le réseau. Il existe quatre réponses, qui ne sont pas des variantes d’un même mécanisme. L’API Anthropic directe envoie une clé statique dans un en-tête x-api-key. Amazon Bedrock signe chaque requête avec des identifiants AWS ; aucune clé Anthropic n’existe dans cette configuration. Google Cloud envoie un jeton d’accès Google à durée de vie limitée. Microsoft Foundry utilise une clé fournie par Azure ou un jeton Microsoft Entra.

Ce guide explique comment intégrer un SDK (kit de développement logiciel) dans un service exécuté sur un serveur Linux. Si vous configurez plutôt l’outil en ligne de commande Claude Code, les variables et le fonctionnement sont différents : consultez configurer Claude Code avec Bedrock ou Vertex. Si le service n’existe pas encore, commencez par le créer en suivant créer une première application Claude API sur un VPS, puis revenez ici pour configurer l’identifiant.

Tout ce qui suit a été vérifié à partir de la documentation de la plateforme Anthropic en août 2026. Les identifiants de modèles, les prix, les versions des SDK et la structure des endpoints évoluent régulièrement. Ce guide renvoie donc vers les pages des fournisseurs au lieu d’afficher des valeurs qui deviennent rapidement obsolètes.

Route 1 : une clé d’API Anthropic

C’est la voie directe, et la seule pour laquelle Anthropic génère le secret. Les requêtes sont envoyées au endpoint Messages sur l’hôte API d’Anthropic, et chaque requête contient trois en-têtes.

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"}]}'

Remplacez MODEL_ID par un identifiant actuel indiqué dans la vue d’ensemble des modèles d’Anthropic. Une réponse correcte est un objet JSON contenant un tableau content et un objet usage. Une clé incorrecte ou expirée renvoie HTTP 401 avec authentication_error. L’absence de l’en-tête anthropic-version provoque une erreur distincte, car cet en-tête est requis pour chaque requête ; les SDK le définissent pour vous.

La construction du client est la plus simple des quatre, car il n’y a rien à construire. Chaque SDK officiel lit automatiquement ANTHROPIC_API_KEY dans l’environnement.

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)

Il est préférable de conserver l’identifiant du modèle dans l’environnement, à côté de la clé. Les noms des modèles changent selon un calendrier que vous ne contrôlez pas, et redéployer le code pour modifier une seule chaîne est un travail évitable.

Les clés sont créées dans la Console, où vous choisissez leur durée de validité au moment de la création : 3 heures, 1 jour, 7 jours ou 30 jours, une durée personnalisée, ou Never. La date d’expiration est définie à la création et ne peut pas être modifiée par la suite. Anthropic envoie un e-mail au créateur de la clé avant l’expiration d’une clé à longue durée, mais une clé à courte durée expire sans aucun avertissement par e-mail. Une clé expirée renvoie 401 et ne peut pas être réactivée. La solution consiste donc toujours à créer une nouvelle clé.

Aucune région n’est à sélectionner pour l’API directe, et la facturation est directement imputée à votre organisation Anthropic. Les workspaces limitent une clé à un seul projet. C’est la méthode la plus claire pour voir ce qu’un service consomme. Pour le calcul correspondant à cette facture, consultez la comparaison des tarifs API par token avec un abonnement.

Une autre option a sa place ici, car elle supprime entièrement le secret statique. Workload Identity Federation permet à un workload d’échanger un token OpenID Connect (OIDC) provenant d’un fournisseur d’identité auquel vous faites déjà confiance contre un token Anthropic à courte durée de validité, auprès de POST /v1/oauth/token. Le SDK renouvelle ce token avant son expiration. Aucune chaîne sk-ant-api... n’est jamais générée ni copiée. Cette solution convient à Kubernetes, GitHub Actions et aux VM cloud, qui disposent déjà d’une identité de plateforme. Un VPS classique ne dispose généralement pas d’un tel émetteur. Sur cette machine, une clé d’API stockée dans un fichier est donc la solution la plus directe, et le reste de ce guide part de ce principe.

Route 2 : identifiants AWS sur Amazon Bedrock

Sur Bedrock, vous n’avez aucune clé Anthropic. Le SDK signe chaque requête HTTP avec AWS Signature Version 4 (SigV4) à l’aide d’identifiants AWS classiques, puis AWS détermine si cette identité peut appeler le modèle.

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

aws sts get-caller-identity affiche le numéro de compte et l’ARN (Amazon Resource Name) de l’identité résolue par vos identifiants. Exécutez cette commande avant toute autre chose. Si elle échoue, l’appel à Claude échouera également, car le SDK parcourt la même chaîne : d’abord les arguments du constructeur, puis les variables d’environnement AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN et AWS_REGION, puis le fichier de configuration AWS et le reste de la chaîne standard (SSO, rôles assumés, rôle de tâche ECS, service de métadonnées d’instance).

La construction du client ne change que sur deux points : la classe et un argument.

from anthropic import AnthropicBedrock

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

La région n’est pas un simple élément décoratif ici. Les endpoints Bedrock sont propres à chaque région, l’accès aux modèles est accordé par région dans la console AWS, et la région fait partie de la signature SigV4. Une signature calculée pour une région est donc rejetée par une autre. Définissez explicitement AWS_REGION dans l’environnement du service. Anthropic précise que le client AnthropicBedrock lit AWS_REGION et utilise us-east-1 si cette variable n’est pas définie. Il ne lit pas ~/.aws/config pour déterminer la région. C’est pourquoi l’AWS CLI peut lister les modèles Claude avec succès sur la même machine alors que votre processus Python échoue : la CLI a lu votre fichier de configuration, contrairement au client.

Sur une instance EC2, vous associez un rôle IAM (identity and access management) et aucun secret n’est écrit sur le disque, car le service de métadonnées d’instance fournit au SDK des identifiants temporaires. Un VPS situé hors d’AWS ne dispose ni d’un rôle d’instance ni d’un service de métadonnées. Vous devez alors choisir entre une paire de clés d’accès longue durée appartenant à un utilisateur IAM et stockée sur la machine, qui constitue le même type de secret qu’une clé Anthropic, et la fédération : vous authentifiez l’utilisateur auprès de votre fournisseur d’identité, appelez AWS STS (security token service), puis utilisez les identifiants temporaires renvoyés. Bedrock accepte également un bearer token via AWS_BEARER_TOKEN_BEDROCK, avec une durée maximale documentée de 12 heures. AWS présente cette méthode comme la moins recommandée.

La facturation est imputée à votre compte AWS plutôt qu’à Anthropic, ce qui est généralement la raison principale de ce choix. Les endpoints régionaux appliquent une majoration de 10 % par rapport à l’endpoint global, selon la documentation disponible en août 2026. Une erreur Bedrock mérite d’être reconnue, car elle ressemble à un problème de permissions alors que ce n’en est pas un : 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. Il s’agit d’un problème de routage du modèle. Modifier les identifiants ne le résoudra pas.

Route 3 : identifiants Google sur Vertex AI

Google Cloud utilise les Application Default Credentials (ADC), avec un ordre de recherche fixe que les bibliothèques d’authentification Google suivent pour trouver un identifiant sans que vous ayez à en indiquer un. ADC vérifie d’abord GOOGLE_APPLICATION_CREDENTIALS, puis le fichier créé par gcloud auth application-default login, puis le compte de service associé via le metadata server.

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

Sur un poste de travail, cette connexion crée $HOME/.config/gcloud/application_default_credentials.json et la configuration est terminée. Sur un serveur, c’est le mauvais outil, car l’identifiant enregistré appartient à une personne et devient inutilisable lorsque son compte est supprimé. En dehors de Google Cloud, il n’y a pas non plus de metadata server. ADC se rabat donc sur GOOGLE_APPLICATION_CREDENTIALS, qui pointe vers un fichier de clé de compte de service. Ce fichier JSON est un secret à longue durée de vie. Il doit être géré exactement comme décrit plus loin dans ce guide. Dans Google Cloud, associez un compte de service à la VM : aucun fichier n’est alors à protéger.

from anthropic import AnthropicVertex

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

Deux éléments changent si vous utilisez directement le protocole HTTP au lieu du SDK. L’identifiant du modèle sort du corps de la requête et passe dans le chemin de l’URL. anthropic_version sort de l’en-tête et passe dans le corps, où il doit être défini sur vertex-2023-10-16. L’identifiant d’authentification est un jeton d’accès Google standard.

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 région est un argument à part entière. global effectue un routage dynamique pour améliorer la disponibilité. us et eu sont des identifiants multirégion. Un nom tel que us-east5 fixe une seule région. Les endpoints multirégion et régionaux coûtent 10 % de plus que l’endpoint global, selon la documentation disponible en août 2026. La facturation passe par le projet Google Cloud. Les quotas et les factures sont donc gérés par Google.

Itinéraire 4 : Microsoft Foundry est l’itinéraire Azure

Si vous avez recherché Claude sur Azure, c’est la section qu’il vous fallait. Une méthode prise en charge existe bien. Claude s’exécute dans Microsoft Foundry (anciennement Azure AI Foundry) et est facturé via Azure Marketplace en unités de consommation Claude. Vous créez une ressource Foundry, vous y déployez un modèle Claude, puis vous appelez un endpoint hébergé dans Azure à l’adresse https://{resource}.services.ai.azure.com/anthropic/v1/*.

Deux types d’identifiants fonctionnent. Le premier est une clé fournie par Azure, disponible dans l’onglet Details du déploiement, dans le portail Foundry. Elle est transmise dans un en-tête api-key ou x-api-key. Le second est un token Microsoft Entra. C’est le meilleur choix sur un serveur, car le contrôle d’accès en fonction du rôle d’Azure détermine alors qui peut appeler l’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"}]}'

Le champ model contient le nom du déploiement, et non un identifiant de modèle. Les deux correspondent par défaut. Ils cessent de correspondre dès que vous attribuez vous-même un nom au déploiement. C’est la cause habituelle d’une erreur Deployment not found sur une requête par ailleurs correcte. Les SDK Python et TypeScript lisent ANTHROPIC_FOUNDRY_API_KEY et ANTHROPIC_FOUNDRY_RESOURCE dans l’environnement. Tous les SDK ne prennent pas en charge Foundry : d’après la documentation d’août 2026, la prise en charge concerne C#, Java, PHP, Python et TypeScript. Les SDK Go et Ruby doivent utiliser le client générique configuré avec l’URL de base Foundry.

Cette solution de contournement présente un risque important. Si ANTHROPIC_API_KEY est encore défini dans l’environnement, le client générique le récupère et envoie votre clé Anthropic à un endpoint Microsoft. Supprimez la variable ou désactivez les valeurs par défaut de l’environnement sur le client. Les tokens Entra expirent après environ une heure. Un processus de longue durée doit donc les renouveler au lieu d’en conserver un seul au démarrage.

Quelle est la durée de validité des identifiants sur votre serveur ?

[
  {
    "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
  }
]

Ces durées maximales et valeurs par défaut sont publiées par chaque fournisseur et ont été relevées en août 2026 ; elles ne résultent pas de mesures. Elles sont importantes pour une raison : elles indiquent combien de temps un identifiant compromis continue de fonctionner pendant que vous découvrez encore la fuite. Les jetons à courte durée de vie au bas du graphique restent valides pendant 1 heure chacun, et le SDK les renouvelle automatiquement. Leur courte durée de vie ne vous impose donc aucune contrainte opérationnelle. Un rôle assumé reste valide pendant 12 heures. Une clé créée avec le préréglage de 30 jours reste valide pendant 720 heures. C’est l’identifiant qui reste pendant un mois dans un fichier sur votre serveur.

Emplacement de l’identifiant d’authentification sur un VPS

Placez le secret dans un fichier que seul root peut lire, puis laissez systemd le transmettre au processus. Cette méthode ne dépend d’aucune version de SDK. Il est donc utile de la mettre en place correctement une fois pour toutes.

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

Le fichier contient des lignes KEY=value simples. N’utilisez ni export, ni guillemets, ni syntaxe shell, car systemd l’analyse directement au lieu de l’exécuter via 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 lit EnvironmentFile= avec les privilèges root, avant de passer à User=claudeapp. Le compte de service n’a donc jamais besoin d’un accès en lecture au fichier. Le mode 600 avec root comme propriétaire suffit. C’est pourquoi la commande install ci-dessus le définit ainsi. Démarrez le service avec sudo systemctl enable --now claude-app, puis vérifiez avec systemctl status claude-app que l’unité a atteint active (running) au lieu de redémarrer en boucle.

Voici quatre choses à éviter, chacune pour une raison que vous pouvez vérifier vous-même :

• N’écrivez pas la clé avec Environment= dans le fichier d’unité. Une unité située sous /etc/systemd/system est lisible par tous. Ainsi, systemctl cat claude-app affiche le secret à n’importe quel utilisateur local.
• Ne validez pas le secret dans le dépôt. .gitignore exclut un nouveau fichier d’un commit, mais ne fait rien pour un fichier déjà validé, car l’historique git conserve tout ce qui lui a été fourni.
• N’intégrez pas le secret dans une image de conteneur. Les lignes ENV et les valeurs --build-arg sont enregistrées dans les layers de l’image, et docker history --no-trunc les affiche. Supprimer le fichier dans un layer ultérieur ne le supprime pas du layer précédent. Transmettez plutôt les secrets au moment de l’exécution avec --env-file ou utilisez un fichier monté.
• Ne considérez pas l’environnement du processus comme privé vis-à-vis de root. sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ affiche la clé. L’objectif est de garder le secret à l’écart de tous les autres comptes du serveur, pas de root, qui peut le lire quelle que soit la méthode utilisée.

Ce dernier point définit la limite de ce que cette conception vous apporte. Une variable d’environnement convient comme conteneur pour un secret lorsque seuls le service et root peuvent la lire. Elle ne convient pas lorsque le processus exécute du code que vous n’avez pas écrit, car tout ce que le processus peut exécuter peut lire son propre environnement. Garder les secrets hors de portée d’un agent IA traite ce cas, qui correspond à un problème différent et nécessite une autre solution.

Comment effectuer la rotation de la clé sans interruption ?

Faites d’abord la rotation, puis révoquez l’ancienne clé.

1. Créez la nouvelle clé dans la Console, dans le même workspace que l’ancienne.
2. Écrivez-la dans /etc/claude-app/env avec sudoedit.
3. Exécutez sudo systemctl restart claude-app.
4. Vérifiez que le service répond aux requêtes, puis révoquez l’ancienne clé dans la Console.

EnvironmentFile est lu au démarrage de l’unité. Un processus en cours d’exécution conserve donc la valeur qui lui a été transmise au lancement. systemctl daemon-reload relit les fichiers d’unité, mais ne modifie pas l’environnement d’un processus en cours d’exécution. Seul un redémarrage prend en compte la nouvelle clé. Si vous révoquez l’ancienne clé à l’étape 1 au lieu de l’étape 4, l’interruption dure jusqu’à l’étape 3.

Les trois autres méthodes effectuent la rotation chez le fournisseur. Un utilisateur IAM peut avoir deux access keys actives simultanément : créez la seconde, déployez-la, puis supprimez la première. Une clé de compte de service Google se renouvelle de la même façon. Une clé Foundry est régénérée dans le portail, ce qui invalide immédiatement l’ancienne. Écrivez donc la nouvelle valeur avant de cliquer. Les tokens Entra et les tokens Anthropic fédérés ne nécessitent aucune rotation. C’est l’argument le plus solide pour les utiliser lorsque c’est possible.

Pendant que vous êtes dans la Console, définissez une limite de dépenses pour le workspace. Une clé divulguée coûte cher avant toute autre conséquence, et limiter les dépenses d’un agent sur un VPS présente les contrôles disponibles.

Pourquoi mon client renvoie-t-il 401 ou 403 ?

401 avec authentication_error sur l’API directe. La clé est incorrecte, révoquée ou expirée. L’expiration est le cas le plus souvent oublié, car le code n’a pas changé et la requête fonctionnait encore hier. Vérifiez la colonne d’expiration de la clé dans la Console, ou lisez expires_at depuis l’Admin API. Cette valeur est null pour les clés sans expiration.

Le SDK ignore votre configuration de federation et utilise une clé à la place. ANTHROPIC_API_KEY et ANTHROPIC_AUTH_TOKEN sont prioritaires sur federation dans l’ordre de priorité des identifiants. L’un ou l’autre prend donc le dessus. Le cas le plus trompeur est le suivant : une variable exportée avec une chaîne vide occupe tout de même son emplacement. Ainsi, ANTHROPIC_API_KEY="" demande au SDK de s’authentifier avec une clé vide au lieu de passer à l’identifiant suivant. Utilisez unset ANTHROPIC_API_KEY.

401 avec le message brut Authentication failed sur federation. Ce message est volontairement identique pour toutes les causes possibles. Un appelant ne peut donc pas déduire la configuration de vos règles en lisant le texte de l’erreur. La cause réelle est enregistrée dans la page d’historique de l’authentification, dans la Console. Consultez cette page avant d’examiner le JWT.

403 sur Foundry. Le token a été authentifié, mais votre compte Azure ne possède pas de rôle autorisant cet appel. Attribuez à l’identité qui effectue la requête un rôle Azure RBAC tel que Foundry User (anciennement Azure AI User) ou Cognitive Services User.

Toute erreur sur Bedrock. Exécutez d’abord aws sts get-caller-identity avec l’utilisateur du service. Cette commande indique si la machine dispose de credentials AWS utilisables. Elle permet de distinguer un problème d’identifiants d’un problème d’accès au modèle ou d’une erreur de région. L’accès au modèle est accordé par région dans la console AWS. Il est donc facile de l’activer dans une région alors que les requêtes sont envoyées vers une autre.

FAQ

Ai-je besoin d’une clé API Anthropic pour utiliser Claude sur Bedrock ou Vertex ?

Non. Sur Amazon Bedrock, le SDK signe chaque requête avec des identifiants AWS à l’aide de SigV4. Sur Google Cloud, il envoie un jeton d’accès Google obtenu via Application Default Credentials. Dans ces deux configurations, aucun secret émis par Anthropic n’est utilisé. La consommation est facturée au compte cloud, et non à Anthropic. C’est également pourquoi une clé Anthropic laissée dans ANTHROPIC_API_KEY représente un risque sur ces hôtes : un client générique configuré pour utiliser un endpoint cloud l’y enverra sans problème.

Claude est-il disponible sur Azure ?

Oui, via Microsoft Foundry, anciennement Azure AI Foundry. Vous créez une ressource Foundry, vous y déployez un modèle Claude, puis vous appelez https://{resource}.services.ai.azure.com/anthropic/v1/messages avec une clé émise par Azure dans un en-tête api-key ou avec un bearer token Microsoft Entra. La consommation est facturée via Azure Marketplace en Claude Consumption Units. Le champ model du corps de la requête doit contenir le nom de votre déploiement. Ce nom n’est identique à l’identifiant du modèle que tant que vous n’avez pas renommé le déploiement.

Où dois-je stocker la clé API Claude sur un serveur Linux ?

Dans un fichier appartenant à root et dont le mode est 600, chargé via EnvironmentFile= dans une unité systemd. systemd lit ce fichier en tant que root avant de basculer vers le User= de l’unité. Le compte de service n’a donc pas besoin d’y accéder. Conservez cette clé hors du dépôt et du fichier d’unité lui-même, qui est lisible par tous et affiché par systemctl cat. Ne la placez pas non plus dans les layers d’une image de conteneur, car docker history --no-trunc réaffiche toute valeur définie avec ENV ou --build-arg.

Pourquoi ma requête API Claude renvoie-t-elle maintenant une erreur 401 alors que rien n’a changé ?

La cause la plus fréquente est l’expiration de la clé à la date définie lors de sa création. L’expiration est définie à la création et ne peut plus être modifiée ensuite. Les clés à courte durée de vie expirent sans avertissement par e-mail. Une clé expirée ne peut pas être réactivée. Créez donc une clé de remplacement, écrivez-la dans le fichier d’environnement, redémarrez le service, puis révoquez l’ancienne clé. Si la clé est bien toujours valide, vérifiez qu’un identifiant obsolète ne la masque pas : ANTHROPIC_API_KEY défini sur une chaîne vide reste prioritaire sur toutes les autres sources d’identifiants.