Clé API Claude Code : variables, fichiers et sécurité (2026)

La clé API de Claude Code n'est pas qu'une chaîne de caractères : elle détermine à quel compte les requêtes sont facturées, quels modèles sont accessibles et l'impact d'une fuite. La plupart des erreurs 401 ne viennent pas d'une clé invalide, mais d'un nom de variable, d'un en-tête de requête ou d'un niveau de configuration incorrect.

Cet article suit l'ordre « chaîne d'authentification, création de la clé, variables et fichiers, configurations multiples, rotation, prévention des fuites, CI et équipe, diagnostic 401 » pour proposer une méthode directement applicable. Les noms de variables et les options exactes dépendent de la version de Claude Code et de la documentation de la passerelle.

Remarque : Claude et Anthropic sont des marques de leurs détenteurs respectifs ; cet article est purement technique et n'implique aucun lien d'affiliation avec ces sociétés. Les interfaces, droits et prix font foi dans la documentation officielle de chaque plateforme et sur les pages du site.

1. Comprendre la chaîne d'authentification de Claude Code

Au démarrage, Claude Code envoie ses requêtes à l'adresse ANTHROPIC_BASE_URL avec des informations d'authentification. Celles-ci proviennent généralement de l'une de deux variables :

ANTHROPIC_AUTH_TOKEN : transmise via Authorization: Bearer, courante pour l'accès par passerelle.
ANTHROPIC_API_KEY : transmise via x-api-key, plus proche du mode natif Anthropic.

La passerelle reçoit la requête, identifie le compte à partir de la clé, puis vérifie le solde, le quota, les droits sur le modèle et la validité. Si un maillon échoue, le symptôme peut être 401, 403 ou 429. Ne vous focalisez donc pas uniquement sur la chaîne de la clé.

Une autre confusion fréquente consiste à lier la clé au modèle. La clé est une identité ; le modèle est un paramètre de requête. Une même clé peut généralement appeler plusieurs modèles, selon les droits du compte et la politique de la passerelle.

2. Créer une clé : cinq étapes

Ouvrez ZSQH AI Gateway ou la plateforme que vous utilisez, inscrivez-vous et connectez-vous à la console.
Allez dans la page « Clés API » et cliquez sur « Nouvelle clé ». Nommez clairement l'environnement et l'usage, par exemple claude-code-travail-mac.
Fixez un plafond de quota et une date d'expiration. Pour une clé de test, commencez bas et ajustez après avoir observé la consommation réelle.
Si la plateforme accepte une liste blanche de modèles ou un périmètre de projet, ne cochez que les modèles nécessaires à Claude Code.
Copiez la clé complète et stockez-la immédiatement dans un gestionnaire de mots de passe ou un service de gestion de secrets. La plupart des consoles ne l'affichent en entier qu'une fois.

Les clés commencent souvent par sk-, mais ce préfixe ne prouve ni l'authenticité ni les droits. Attention aux espaces et retours à la ligne en début et fin lors du copier-coller : c'est une cause fréquente de 401.

Après la création, validez avec une requête curl minimale avant de distribuer la clé aux membres de l'équipe. La méthode est décrite dans la section « Diagnostic 401 ».

3. Variables d'environnement et fichiers de configuration : que choisir

Méthode	Cas d'usage	Avantages	Attention
Variables du shell	Poste de développement, bascule ponctuelle	Rien n'est écrit dans le projet, changement simple	Un nouveau terminal ou l'IDE peut ne pas les lire
settings.json utilisateur	Usage personnel durable	Configuré une fois, effectif partout	Clé stockée en clair
settings.local.json du projet	Remplacement pour un seul projet	N'affecte pas les autres projets, peut être ignoré par Git	À reconfigurer sur une autre machine
apiKeyHelper ou gestion de secrets	Équipe, machine partagée, conformité	La clé n'apparaît pas directement dans le fichier	Script et gestion des droits supplémentaires
Variables secrètes de CI	Chaîne automatisée	Séparées du code, auditables	Masquage des journaux et droits de branche à vérifier

Les variables d'environnement conviennent à « je veux tester tout de suite » ; settings.json à « cette machine doit fonctionner ainsi durablement » ; la gestion de secrets à « la clé ne doit pas apparaître en clair sur le disque ». Les trois peuvent se superposer, mais il faut savoir qui écrase qui. La priorité de configuration de Claude Code va globalement de la configuration d'entreprise aux paramètres de ligne de commande, puis au projet local, au projet et à l'utilisateur ; les versions peuvent ajuster ce point, référez-vous à la documentation officielle.

Un piège classique : vous exportez la variable dans ~/.zshrc, mais Claude Code lancé depuis le Dock ou un IDE ne la voit pas. Une application graphique hérite de l'environnement de session, pas nécessairement de votre configuration shell. Dans ce cas, modifiez settings.json ou injectez la variable explicitement dans le script de lancement.

4. Configurations multiples : isoler personnel, projet et équipe

Prévoyez au moins trois clés : usage personnel quotidien, projet dédié et automatisation. Leurs quotas, droits et cycles de rotation diffèrent ; les mélanger rend la consommation et les incidents difficiles à localiser.

Si vous ne voulez pas maintenir plusieurs fichiers, injectez la configuration par scénario avec des fonctions shell :

# ~/.zshrc
claude_work() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_WORK_KEY" \
  claude "$@"
}

claude_test() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_TEST_KEY" \
  claude "$@"
}

Placez les vraies clés dans ~/.zshrc.local ou dans un gestionnaire de secrets ; le fichier principal ne référence que les variables. Changer d'environnement ne demande alors que de changer de fonction, sans toucher au code du projet.

Pour l'isolation par projet, utilisez .claude/settings.local.json et vérifiez qu'il figure dans .gitignore. Le fichier .claude/settings.json partagé par l'équipe ne doit contenir que des éléments non sensibles : URL de base, nom de modèle, permissions. Jamais de clé.

5. Rotation des clés : quand et comment

La rotation n'est pas un formalisme : elle réduit la fenêtre d'exposition après une fuite. Changez de clé lors d'un départ ou d'une mutation, d'une perte d'appareil, d'un doute sur une fuite, d'une exigence du fournisseur, et à intervalle régulier. La période peut suivre les règles de conformité de l'équipe, par exemple tous les 90 jours.

Créez une nouvelle clé dans la console, avec la date dans le nom, par exemple claude-code-prod-2026-10.
Écrivez d'abord la nouvelle clé dans le gestionnaire de secrets ou les variables, sans supprimer l'ancienne.
Validez une fois avec curl et une fois avec Claude Code : modèles, quota et droits doivent fonctionner.
Consultez les journaux d'usage de l'ancienne clé pour vérifier qu'aucun script ou membre ne l'utilise encore.
Désactivez l'ancienne clé, puis surveillez le taux d'erreur pendant un à deux jours.
Notez la date de rotation, le responsable et le périmètre concerné pour la prochaine passation.

N'effectuez pas la rotation pendant un pic de production. Faire tourner deux clés en parallèle un moment est bien plus sûr que « supprimer puis recréer ».

6. Prévenir les fuites : du poste de développement au dépôt

Les fuites de clés viennent rarement d'une attaque : plus souvent d'un commit personnel, d'une capture d'écran, d'un enregistrement d'écran, d'un message de groupe ou d'un journal. Quelques règles :

.gitignore doit couvrir .env, .env.*, .claude/settings.local.json, *.pem, etc.
Avant commit, utilisez un scan de secrets ou un hook pre-commit pour détecter les motifs sk-.
N'écrivez pas de clé par défaut dans le code et ne déboguez pas avec echo $ANTHROPIC_AUTH_TOKEN.
Masquez les en-têtes Authorization, x-api-key et similaires dans les journaux.
Avant un partage d'écran ou une capture, fermez l'historique du terminal ou effacez l'écran.
Restreignez les permissions des fichiers de développement, par exemple chmod 600 ~/.claude/settings.json.
Utilisez des clés avec expiration et plafond pour limiter l'impact d'une fuite.

En cas de fuite confirmée, l'ordre est : désactiver ou supprimer la clé, créer une nouvelle clé, puis examiner les journaux d'usage et l'historique du dépôt. Changer un mot de passe ou supprimer un fichier ne suffit pas, car l'ancienne clé a pu être copiée ailleurs.

7. CI et usage en équipe

En CI, le principe est que « la clé n'entre ni dans le code, ni dans l'image, ni dans les journaux ». Concrètement :

Injectez-la via le mécanisme de secrets ou de variables d'environnement de la plateforme ; ne l'écrivez pas en clair dans le YAML.
Limitez le secret aux branches protégées ou aux workflows de confiance.
Vérifiez avant toute sortie de journal que les en-têtes ne sont pas imprimés ; la plupart des bibliothèques HTTP ne les affichent pas, mais un journal personnalisé peut le faire.
Utilisez une clé distincte pour les tâches automatisées, avec un quota séparé, pour localiser les anomalies.
Une clé par membre, désactivée le jour du départ ; ne mutualisez pas une clé pour simplifier.
Exportez régulièrement l'usage et recoupez-le par membre, projet et modèle.

Si la plateforme propose des identifiants de courte durée ou OIDC, privilégiez-les pour réduire le stockage de clés durables. La disponibilité dépend de la plateforme ; consultez la documentation avant l'intégration.

8. Diagnostic 401 : l'ordre à suivre

Un 401 signale un échec d'authentification, pas nécessairement une clé erronée. Suivez cet ordre ; le diagnostic prend généralement quelques minutes :

Vérifiez l'URL de base utilisée avec echo $ANTHROPIC_BASE_URL. Une valeur vide ou une ancienne adresse provoquera un échec.
Vérifiez que la clé n'a ni espace, ni saut de ligne, ni guillemet superflu ; recopiez-la depuis la console.
Vérifiez le nom de variable : ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY, sans définir les deux à la fois.
Vérifiez que l'en-tête correspond à l'attente de la passerelle : Bearer ou x-api-key.
Vérifiez que la clé n'est ni expirée ni désactivée et que le compte dispose d'un solde.
Vérifiez que le nom du modèle existe dans le catalogue de la passerelle ; certaines plateformes renvoient 401 ou 403 pour un modèle absent de vos droits.
Si un proxy s'interpose, vérifiez qu'il ne retire ou ne réécrit pas l'en-tête Authorization.
Reproduisez avec un curl minimal pour écarter la version de Claude Code ou le niveau de configuration.

Tableau des erreurs courantes :

Erreur	Cause fréquente	Traitement
401 Unauthorized	Clé erronée, mauvais nom de variable, en-tête incorrect	Recopier la clé ; ne garder qu'une variable d'authentification
403 Forbidden	Clé sans droit sur le modèle ou restriction IP	Vérifier liste blanche et droits sur le modèle
404 Not Found	URL de base ou chemin incorrect	Valider successivement l'adresse racine et `/v1`
429 Too Many Requests	Concurrence ou quota dépassé	Réduire la concurrence ; vérifier le quota de la clé
insufficient quota	Solde insuffisant	Recharger ou changer de clé

Si curl fonctionne mais que Claude Code renvoie encore 401, examinez l'environnement de lancement : le terminal intégré de l'IDE, Docker, systemd ou launchd peuvent ne pas hériter des variables du shell. Écrire la configuration dans settings.json ou dans le script de lancement résout généralement le problème.

Questions fréquentes

La clé de Claude Code est-elle la même que l'abonnement Claude web ?

Non. L'abonnement web est un produit de chat ; la clé API est un identifiant d'interface. Claude Code passe par des appels API et ne peut pas remplacer la clé par un abonnement web.

Une même clé peut-elle servir à Claude Code et à Cursor ?

Techniquement, oui, si les deux outils acceptent le même protocole de passerelle et les mêmes noms de modèles. Il est toutefois préférable de séparer les clés par outil pour appliquer des quotas distincts, diagnostiquer et désactiver plus facilement.

La clé est-elle en sécurité dans settings.json ?

Sur un ordinateur personnel, cela peut être acceptable, car le fichier reste local. Sur une machine partagée, dans un dépôt ou en CI, n'y placez jamais de clé en clair : utilisez des variables d'environnement, apiKeyHelper ou un service de gestion de secrets.

La rotation impose-t-elle une interruption de service ?

Non. Créez et validez la nouvelle clé, basculez la configuration, puis désactivez l'ancienne. Faire coexister les deux clés un moment évite toute coupure.

Pourquoi une clé qui fonctionnait hier renvoie-t-elle 401 aujourd'hui ?

Causes fréquentes : expiration, solde ou quota épuisé, clé désactivée par un administrateur, changement de méthode d'authentification côté passerelle, ou environnement de lancement qui n'a pas chargé les dernières variables. Suivez l'ordre de diagnostic 401 point par point.

Étape suivante

Si vous n'avez pas encore de clé, créez-en une à faible quota depuis la page d'inscription, puis configurez et validez selon l'ordre de cet article. Les modèles, quotas et modes de facturation sont décrits sur la page Tarifs des modèles ; les prix évoluent avec les versions de modèles et les politiques amont, référez-vous aux informations en temps réel de la page.

Pour aller plus loin :

Remarque : Claude, Claude Code et Anthropic sont des marques de leurs détenteurs respectifs ; cet article est purement technique et n'implique aucun lien d'affiliation avec ces sociétés. Les interfaces, droits et prix font foi dans la documentation officielle de chaque plateforme.