Chaque intégration Stripe commence par la même question : quelle clé va où ? Stripe vous fournit une clé publiable, une clé secrète et la possibilité de générer des clés restreintes, chacune en version test et en version live. Mettez la mauvaise au mauvais endroit et vous exposez soit la capacité de déplacer de l'argent, soit vous perdez un après-midi sur une erreur 401. Ce guide couvre ce que fait chaque clé API Stripe, où elle se trouve, comment envoyer une première requête en mode test et comment garder la clé live à l'écart de tout ce qui est partagé. Pour le concept général d'abord, commencez par ce qu'est une clé API. Tout ce qui suit s'appuie sur la documentation des clés API de Stripe, vérifiée en septembre 2026.
Où se trouvent vos clés API Stripe dans le Dashboard
Ouvrez la page des clés API à l'adresse dashboard.stripe.com/apikeys. Elle se trouve sous Developers dans le Dashboard et affiche les clés du compte ou du sandbox que vous consultez. Un bouton bascule entre le mode sandbox et le mode live, et la liste des clés change avec lui.
La page comporte deux listes :
- Clés standard contient votre clé publiable et votre clé secrète.
- Clés restreintes contient toutes les clés que vous avez créées avec des permissions délimitées.
La visibilité diffère selon le mode. Dans un sandbox, vous pouvez révéler chaque clé à tout moment. En mode live, une clé secrète que vous créez vous-même n'est affichée qu'une seule fois, à la création. Copiez-la dans votre coffre-fort avant de fermer la boîte de dialogue ; la perdre signifie devoir la faire tourner. Seules les clés par défaut générées par Stripe peuvent être révélées à nouveau en mode live.
Une chose que la page ne montre pas : les secrets de signature des webhooks. Ceux-ci se trouvent sous Webhooks, par endpoint, et ne sont pas du tout des clés API.
Clés publiables vs clés secrètes
Les noms décrivent la frontière de confiance.
| Clé | Préfixe | Sûre à exposer | Ce qu'elle peut faire |
|---|---|---|---|
| Publiable | pk_test_ / pk_live_ |
Oui | Identifier votre compte, créer des tokens et des PaymentMethods à partir des données de carte dans Stripe.js, Elements et les SDK mobiles |
| Secrète | sk_test_ / sk_live_ |
Non | Tout : créer des paiements, émettre des remboursements, lire les données clients, déclencher des virements |
| Restreinte | rk_test_ / rk_live_ |
Non | Uniquement les ressources et permissions que vous accordez |
Une clé publiable a sa place dans le navigateur ou l'application mobile. Elle transforme un numéro de carte en token et guère plus. Elle ne peut pas créer de paiement ni lire les données du compte, donc l'inclure dans du code front-end est attendu.
Une clé secrète a sa place sur votre serveur et nulle part ailleurs. Les recommandations de Stripe ont évolué : la documentation indique désormais qu'ils « ne recommandent pas d'utiliser les clés secrètes pour de nouveaux cas d'usage » et renvoient vers les clés restreintes. La clé secrète non restreinte fonctionne toujours, mais traitez-la comme une solution de dernier recours, pas comme la valeur par défaut.
Clés en mode test vs mode live
Stripe fait tourner deux mondes séparés, chacun avec son propre jeu de clés. Les clés de test (la documentation récente appelle le côté test un sandbox, bien que les préfixes indiquent toujours _test_) renvoient des objets simulés : faux clients, faux PaymentIntents, cartes de test qui réussissent ou échouent sur commande, pas d'argent réel. Les clés live atteignent les réseaux de cartes et déplacent de vrais fonds.
La séparation est stricte. Un client créé avec sk_test_ n'existe pas du point de vue de sk_live_, et inversement. Le code d'erreur de Stripe pour le croisement des flux, livemode_mismatch, le dit clairement : « Les clés API, requêtes et objets en mode test et live ne sont disponibles que dans le mode correspondant. »
Deux règles pratiques en découlent :
- Développez et testez entièrement avec
sk_test_ourk_test_. Stripe recommande un sandbox général distinct pour les nouvelles intégrations afin que ses paramètres et données restent isolés. - Passer en live est un changement de configuration, pas un changement de code. Votre serveur lit la clé depuis une variable d'environnement ou un coffre-fort, et passer en production revient à changer cette valeur.
Chaque réponse de l'API inclut un booléen livemode. Vérifiez-le dans vos tests ; c'est la protection la moins coûteuse contre un déploiement avec la mauvaise clé.
Clés restreintes et moindre privilège
Une clé API restreinte (que Stripe abrège en RAK) est une clé secrète dotée d'un masque de permissions. Lorsque vous en créez une, vous choisissez une permission pour chaque groupe de ressources : None, Read ou Write. Tout est par défaut à None. Write inclut Read, et la correspondance avec HTTP est simple : GET nécessite Read, POST et DELETE nécessitent Write.
Pour en créer une, cliquez sur Create restricted key sur la page des clés API, choisissez un ensemble de permissions préconfiguré ou partez de zéro, nommez-la, définissez les permissions et complétez l'invite à deux facteurs. Comme pour une clé secrète que vous créez vous-même en mode live, vous ne voyez la valeur qu'une seule fois.
Le guide des clés restreintes suggère une clé par service : un service de facturation obtient Write sur Invoices et Customers, une tâche de reporting obtient Read sur Charges et Disputes. Si un service est compromis, l'attaquant est enfermé dans les permissions de cette clé. Une clé en lecture seule sur les litiges ne peut pas créer de paiement ni toucher à un virement.
Accordez de larges permissions à une nouvelle clé dans un sandbox, lancez votre suite de tests, puis ouvrez les logs de requêtes de la clé (menu déroulant, View request logs) et élaguez chaque permission qui n'a vu aucun trafic. Stripe vous permet aussi d'étiqueter les clés destinées aux agents IA autonomes afin qu'elles relèvent des règles d'approbation pour les virements et les remboursements ; utilisez ce chemin plutôt qu'une simple clé secrète.
Votre première requête avec curl et Python
Stripe s'authentifie avec HTTP Basic Auth : la clé est le nom d'utilisateur et le mot de passe est vide. Le deux-points final indique à curl de ne pas demander d'invite :
export STRIPE_API_KEY=sk_test_... # your sandbox secret key
curl https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_API_KEY:" \
-d amount=2000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]=true"
La réponse est un PaymentIntent avec un id commençant par pi_, status: "requires_payment_method" et livemode: false. Ce dernier champ confirme que vous avez utilisé une clé de test.
Stripe accepte aussi -H "Authorization: Bearer $STRIPE_API_KEY", qui est la forme utilisée par Apidog et la plupart des clients HTTP. Les deux portent la même clé ; si vous ne savez pas quel style convient à votre stack, notre comparaison des clés API et des bearer tokens couvre les compromis. Les requêtes doivent passer en HTTPS ; le HTTP simple échoue d'emblée, selon la référence d'authentification.
En Python, le modèle actuel du SDK est un StripeClient qui lit la clé depuis l'environnement :
import os
import stripe
client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])
intent = client.v1.payment_intents.create({
"amount": 2000,
"currency": "usd",
"automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode) # pi_..., False
Aucune chaîne de clé n'apparaît dans le fichier. Le même code s'exécute contre le test ou le live selon ce que l'environnement fournit.
Laissez votre agent de codage tester la clé Stripe avec Apidog CLI
Curl prouve que la clé fonctionne une fois. Votre agent de codage peut en faire une vérification répétable via Apidog CLI et garder la clé hors du projet partagé. Configurez-le une fois (le token se trouve sous Account Settings, API Access Token) :
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Ensuite, donnez à l'agent une seule invite :
Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.
Les commandes qu'il exécute, vérifiées avec Apidog CLI 2.2.7 :
apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
--env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json
L'invite précise l'encodage de formulaire parce que les endpoints v1 de Stripe n'acceptent pas le JSON. L'assertion livemode est votre fil-piège : si quelqu'un exécute le cas avec une clé live, il échoue avant qu'une seconde requête ne parte. En CI, la même ligne apidog run lit la clé depuis le magasin de secrets de votre pipeline ; notre guide sur le pipeline CI/CD avec Apidog CLI en propose une version prête à copier-coller. La définition de la requête est partagée ; le credential live ne l'est jamais.
Faire tourner les clés et que faire si l'une fuite
Le guide de gestion des clés de Stripe est sans détour : considérez que tout ce qui a été commité dans un dépôt, collé dans un chat ou imprimé dans un log est compromis, même si vous n'êtes pas sûr que quelqu'un l'ait vu.
La rotation est intégrée au Dashboard. Depuis le menu déroulant d'une clé, choisissez Rotate key, définissez une expiration pour l'ancienne clé et copiez la remplaçante. Les deux fonctionnent pendant la période de grâce, jusqu'à 7 jours, ce qui vous permet de déployer progressivement et de surveiller les logs de requêtes pour repérer les retardataires. Now révoque l'ancienne clé immédiatement.
Si une clé secrète ou restreinte fuite :
- Faites-la tourner immédiatement avec une expiration courte.
- Mettez à jour chaque serveur qui l'utilisait, confirmez le trafic dans les logs de requêtes, puis laissez l'ancienne clé expirer.
- Passez en revue l'activité récente dans Workbench pour tout ce que votre intégration ne ferait pas : comptes connectés non reconnus, virements que vous n'avez pas initiés, nouveaux comptes bancaires.
- Mettez en pause les virements suspects, inversez ceux déjà envoyés et remboursez rapidement les paiements frauduleux pour devancer les litiges.
- Faites aussi tourner vos autres clés. Si une a fuité, supposez que le canal par lequel elle a fuité en a vu d'autres.
Stripe scanne les clés exposées et vous avertira, parfois en désactivant proactivement la clé, mais la détection n'est pas garantie. Chercher sk_live_ et rk_live_ dans vos dépôts et votre configuration CI est un audit de cinq minutes, et un scanner de secrets dans un hook de pré-commit empêche la prochaine fuite. Stripe ne demande jamais votre clé secrète, donc tout message qui la demande est du phishing.
Erreurs courantes de clés API Stripe
| Symptôme | Ce que cela signifie | Correction |
|---|---|---|
401 « No valid API key provided » |
Clé manquante, malformée ou révoquée | Vérifiez l'en-tête ; confirmez que la clé n'a pas été changée |
api_key_expired |
La clé a été changée ou a expiré | Récupérez la clé actuelle depuis le Dashboard |
secret_key_required |
Vous avez envoyé une clé pk_ à un endpoint côté serveur |
Utilisez sk_ ou rk_ côté backend |
resource_missing sur un id dont vous savez qu'il existe |
Mauvais mode : clé de test contre un objet live, ou l'inverse | Faites correspondre le mode de la clé à celui de l'objet |
403 « doesn't have permissions to perform the request » |
La clé restreinte n'a pas Read ou Write sur cette ressource | Modifiez les permissions de la clé ; le corps de l'erreur indique ce qui manque |
livemode_mismatch |
Mélange de clés ou d'objets de test et live dans une même requête | Gardez chaque environnement entièrement dans un seul mode |
Les cas 401 et 403 correspondent à stripe.AuthenticationError et stripe.PermissionError dans le SDK Python, selon la référence des erreurs, ce qui vous permet de les intercepter spécifiquement. Un cas moins évident : une clé live qui n'a pas créé de virements ou de payouts pendant 180 jours est limitée pour ces actions, avec une option Restore access sur la clé.
FAQ
Est-il sûr de mettre une clé publiable Stripe dans mon code frontend ?
Oui. Une clé pk_ transforme les données de carte en token mais ne peut pas créer de paiements, lire des clients ni déplacer de l'argent. Seules les clés secrètes et restreintes restent côté serveur.
Puis-je utiliser une clé restreinte en mode test ?
Oui. Les clés restreintes existent dans les deux modes (rk_test_ et rk_live_). Stripe recommande de régler d'abord la version de test, puis de créer une clé live avec des permissions correspondantes.
Le secret de signature du webhook est-il identique à ma clé API ?
Non. Les secrets de signature sont émis par endpoint de webhook et servent uniquement à vérifier qu'un événement entrant provient bien de Stripe. Ils se trouvent sous Webhooks, pas sur la page des clés API. Si vous mettez cela en place, voyez comment tester les webhooks Stripe en CI.
Que se passe-t-il si j'utilise une clé de test en production ?
Les requêtes réussissent mais aucune carte n'est débitée et aucun argent ne bouge. Comme livemode revient à false sur chaque objet, une assertion sur ce champ détecte l'erreur avant vos clients.
La version courte
Les clés publiables vont dans le client, les clés secrètes et restreintes restent sur le serveur, test et live ne se mélangent jamais, et une clé restreinte l'emporte sur une clé secrète dès que vous pouvez la délimiter. Gardez la clé live dans un coffre-fort, passez la clé de test à Apidog CLI au moment de l'exécution, et conservez une assertion livemode dans chaque cas de test que votre agent écrit.