Clés API
Utilisez des clés API pour authentifier vos requêtes API.
Stripe authentifie vos requêtes API grâce aux clés API de votre compte. Si une requête ne contient pas de clé valide, Stripe renvoie une erreur de requête non valide. Si une requête contient une clé supprimée ou expirée, Stripe renvoie une erreur d’authentification.
Utilisez le Dashboard des développeurs pour créer, révéler, supprimer et renouveler les clés API. Pour accéder à vos clés API v1, sélectionnez l’onglet Clés API dans votre Dashboard.
Types de clés
Par défaut, tous les comptes disposent de quatre clés API au total, deux dans un environnement de test et deux en mode production :
- Clé secrète de l’environnement de test : utilisez cette clé pour authentifier les requêtes sur votre serveur lorsque vous effectuez des tests dans un environnement de test. Par défaut, vous pouvez utiliser cette clé pour effectuer toutes les requêtes API sans restriction. Réservez cette clé pour les activités de test et de développement de manière à ne pas risquer de modifier par accident des paiements ou des clients réels.
- Clé publiable de l’environnement de test : utilisez cette clé à des fins de test dans le code côté client de votre application Web ou mobile. Réservez cette clé pour les activités de test et de développement de manière à ne pas risquer de modifier par accident des paiements ou des clients réels.
- Clé secrète du mode production : utilisez cette clé pour authentifier les requêtes sur votre serveur en mode production. Par défaut, vous pouvez l’utiliser pour effectuer n’importe quelle requête API sans restriction.
- Clé publiable du mode production : utilisez cette clé dans le code côté client de votre application Web ou mobile lorsque votre application est prête à être lancée.
Vos clés secrète et publiable se trouvent dans l’onglet Clés API du Dashboard. Si vous ne pouvez pas afficher vos clés API, demandez au propriétaire de votre compte Stripe de vous ajouter à son équipe avec les autorisations appropriées.
Clés API limitées
Vous pouvez générer des clés API restreintes dans le Dashboard pour permettre un accès personnalisé et limité à l’API. Cependant, Stripe ne propose pas de clés restreintes par défaut.
Lorsque vous êtes connecté(e), Stripe inclut automatiquement vos clés API de test dans les exemples de code de notre documentation. Personne d’autre que vous ne peut voir ces valeurs. Si vous n’êtes pas connecté(e), les exemples de code contiennent des clés API générées de manière aléatoire. Vous pouvez les remplacer par vos propres clés de test ou vous connecter pour voir les exemples de code remplis avec vos clés API de test.
Le tableau suivant contient des exemples de clés API de test secrète et publique générées de manière aléatoire :
| Type | Valeur | Utilisation |
|---|---|---|
| Secrète | sk_ | Côté serveur : doit être gardée secrète et stockée en toute sécurité dans le code côté serveur de votre application Web ou mobile (par exemple, dans une variable d’environnement ou un système de gestion des identifiants) pour effectuer des appels aux API Stripe. Cette clé ne doit pas être affichée sur un site Web ou intégrée dans une application mobile. |
| Publiable | pk_ | Côté client : peut être publiquement accessible dans le code côté client de votre application Web ou mobile (checkout.js, par exemple) pour collecter les informations de paiement de façon sécurisée, comme avec Stripe Elements. Par défaut, Stripe Checkout collecte les informations de paiement de façon sécurisée. |
| Limitée | Une chaîne commençant par rk_ | Dans des microservices : doit être gardée secrète et stockée en toute sécurité dans votre code de microservice pour effectuer des appels aux API Stripe. Cette clé ne doit pas être affichée sur un site Web ou intégrée dans une application mobile. |
Environnement de test ou mode production
Toutes les requêtes à l’API Stripe s’effectuent en mode d’environnement de test ou en mode production. Utilisez un environnement de test pour accéder aux données de test, et le mode production pour accéder aux données réelles du compte. Chaque mode possède son propre jeu de clés API. Les objets accessibles dans un mode ne le sont pas dans l’autre. Par exemple, un objet Product d’environnement de test ne peut pas être utilisé dans le cadre d’un paiement en mode production.
Accès aux clés API en mode production
Vous ne pouvez révéler qu’une seule fois une clé API secrète ou limité en mode production. Si vous la perdez, vous ne pourrez pas la récupérer depuis le Dashboard. Dans ce cas, renouvelez la clé ou supprimez-la et créez-en une nouvelle.
| Type | Quand l’utiliser | Objets | Comment l’utiliser | Considérations |
|---|---|---|---|---|
| environnements de test | Utilisez un environnement de test et les clés API test associées au fur et à mesure que vous développez votre intégration. Dans un bac à sable, les réseaux de cartes et les prestataires de services de paiement ne traitent pas les paiements. | Les appels à l’API renvoient des objets fictifs. Vous pouvez par exemple récupérer et utiliser des objets account, payment, customer, charge, refund, transfer, balance et subscription de test. | Utilisez des cartes et des comptes de test. Vous ne pouvez pas accepter de moyens de paiement réels ni utiliser de vrais comptes. | Identity n’effectue aucun contrôle de vérification. Les objets Account de Connect ne renvoient pas de champs sensibles. |
| mode production | Utilisez le mode production et les clés API de production correspondantes au moment de lancer votre intégration et de commencer à accepter des fonds. En mode production, les paiements sont réellement traités par les réseaux de cartes et fournisseurs de services de paiement. | Les appels à l’API renvoient des objets réels. Vous pouvez par exemple récupérer et utiliser des objets account, payment, customer, charge, refund, transfer, balance et subscription réels. | Acceptez des cartes bancaires réelles et utilisez de vrais comptes client. Vous pouvez accepter des paiements, autorisations de paiement et captures réels à partir de cartes bancaires et de comptes. | Les litiges ont un flux plus nuancé et un processus de test plus simple. En outre, certains moyens de paiement ont un flux plus nuancé et nécessitent plus d’étapes. |
Modifier une clé API
Le renouvellement d’une clé la révoque et génère une clé de remplacement. Vous pouvez renouveler une clé immédiatement ou programmer le renouvellement après un certain temps. Renouvelez une clé dans des scénarios tels que les exemples suivants :
- Vous perdez une clé secrète ou une clé limitée en mode production, et ne pouvez pas la récupérer à partir du Dashboard ; vous devez alors la remplacer.
- L’une de vos clés secrètes ou limitées est compromise, et vous devez la révoquer pour bloquer toute requête à l’API potentiellement malveillante.
- Votre politique exige de révoquer les clés à intervalles réguliers.
Pour renouveler une clé API :
- Ouvrez la page Clés API.
- Sur la ligne correspondant à la clé que vous souhaitez renouveler, cliquez sur le menu de dépassement (), puis sélectionnez Renouveler la clé.
- Choisissez une date d’expiration dans le menu déroulant Expiration.
- Cliquez sur Rotation de la clé API.
- La boîte de dialogue affiche la nouvelle valeur de la clé. Copiez-la en cliquant dessus.
- Enregistrez la valeur de la clé. Vous ne pourrez pas la récupérer plus tard.
- Dans le champ Ajouter une note, saisissez l’emplacement où vous avez enregistré la clé et cliquez sur Terminé ou sur Enregistrer.
Si vous choisissez Maintenant pour le champ Expiration, nous supprimons l’ancienne clé. Si vous avez sélectionné une autre durée, le temps restant avant l’expiration de la clé s’affiche sous son nom.
Vous pouvez utiliser la nouvelle clé immédiatement, indépendamment de la date d’expiration de l’ancienne clé.
Lorsque vous renouvelez une clé publiable, le nom de la clé de remplacement est toujours Publishable key. Lorsque vous renouvelez une clé secrète, le nom de la clé de remplacement est toujours Secret key. Lorsque vous renouvelez une clé limitée, la clé de remplacement garde le nom de la clé initiale. Vous pouvez renommer une clé secrète ou limitée en cliquant sur son menu déroulant et en sélectionnant Modifier la clé.
Afficher les logs de requêtes API
Pour ouvrir les logs des requêtes API, cliquez sur le menu de débordement () de n’importe quelle clé, puis sélectionnez Afficher les logs des requêtes. L’ouverture des logs vous redirige vers le Dashboard Stripe principal.
Clés secrètes et limitées
Utilisez le Dashboard pour créer, supprimer, afficher et modifier des clés secrètes et limitées.
Créer une clé API secrète
Pour créer une clé API secrète :
- Ouvrez la page Clés API.
- Cliquez sur Créer une clé secrète.
- Stripe envoie un code de vérification sur votre adresse e-mail ou par SMS (l’e-mail ou le SMS peut prendre un certain temps à arriver). Saisissez le code dans la boîte de dialogue. Au besoin, cliquez sur Continuer pour poursuivre.
- Saisissez un nom dans le champ Nom de la clé.
- Cliquez sur Créer.
- La boîte de dialogue affiche la nouvelle valeur de la clé. Copiez-la en cliquant dessus.
- Enregistrez la valeur de la clé. Vous ne pourrez pas la récupérer plus tard.
- Dans le champ Ajouter une note, saisissez l’emplacement où vous avez enregistré la clé et cliquez sur Terminé.
Créer une clé API limitée
Une clé API limitée accorde uniquement le niveau d’accès que vous spécifiez.
Pour créer une clé API limitée :
- Ouvrez la page Clés API.
- Vous pouvez créer une clé limitée de toutes pièces ou dupliquer une clé limitée existante.
- Pour créer une clé limitée de toutes pièces, cliquez sur Créer une clé limitée. Dans ce cas, la valeur par défaut pour toutes les autorisations est Aucune.
- Pour cloner une clé existante, cliquez sur le menu déroulant () et sélectionnez Dupliquer la clé dans la ligne correspondant à la clé que vous souhaitez cloner. Dans ce cas, la valeur par défaut de chaque autorisation correspond à la valeur concernée de la clé clonée.
- Dans le champ Nom de la clé, saisissez un nom. Si vous avez dupliqué une clé existante, le nom par défaut est celui de la clé dupliquée.
- Pour chaque ressource à laquelle la nouvelle clé doit accéder, sélectionnez l’autorisation voulue. Si vous utilisez Connect, vous pouvez également sélectionner l’autorisation à accorder lors de l’accès aux comptes connectés avec cette clé. Les autorisations disponibles sont Aucune, Lecture ou Écriture.
- Cliquez sur Créer une clé.
- Stripe envoie un code de vérification sur votre adresse e-mail ou par SMS (l’e-mail ou le SMS peut prendre un certain temps à arriver). Saisissez le code dans la boîte de dialogue. Au besoin, cliquez sur Continuer pour poursuivre.
- La boîte de dialogue affiche la nouvelle valeur de la clé. Copiez-la en cliquant dessus.
- Enregistrez la valeur de la clé. Vous ne pourrez pas la récupérer plus tard.
- Dans le champ Ajouter une note, saisissez l’emplacement où vous avez enregistré la clé et cliquez sur Terminé.
Supprimer une clé API secrète ou limitée
Si vous supprimez une clé, toutes les parties de votre code qui utilisent cette clé ne pourront plus effectuer d’appels à l’API. Après avoir supprimé une clé, créez-en une nouvelle et mettez à jour votre code pour l’utiliser.
Remarque
Vous ne pouvez pas supprimer une clé publiable.
Pour supprimer une clé :
- Dans le Dashboard des développeurs, sélectionnez l’onglet Clés API.
- Repérez la clé que vous souhaitez supprimer dans la liste Clés standard ou Clés limitées. Cliquez sur le menu déroulant () dans la ligne correspondant à cette clé, puis sélectionnez Supprimer la clé.
- Si vous êtes sûr(e) de vouloir supprimer la clé, cliquez sur Supprimer la clé dans la fenêtre intitulée Supprimer la clé API. Sinon, cliquez sur Annuler.
Révéler une clé API secrète dans un environnement de test
Avec les environnements de test, vous pouvez révéler une clé API secrète autant de fois que vous le souhaitez.
Pour révéler une clé secrète dans un environnement de test :
- Dans le Dashboard des développeurs, sélectionnez l’onglet Clés API.
- Dans la liste **Clés Standard **, à la ligne Clé secrète, cliquez sur Révéler la clé de test.
- Copiez la valeur de la clé en cliquant dessus.
- Enregistrez la valeur de la clé.
- Cliquez sur Masquer la clé de test.
Révéler une clé API secrète ou limitée pour le mode production
En mode production, Stripe n’affiche les clés API secrètes ou limitées qu’une seule fois (pour des raisons de sécurité). Enregistrez la clé dans un endroit où vous ne risquez pas de la perdre. Pour vous souvenir de l’endroit où vous l’avez stockée, vous pouvez ajouter une note à ce propos dans le Dashboard. Si vous perdez la clé, vous pouvez l’invalider ou la supprimer et en créer une autre.
Vous ne pouvez pas révéler une clé secrète que vous avez créée en mode production
Une fois que vous avez créé une clé API secrète ou limitée en mode production, nous l’affichons avant que vous ne l’enregistriez. Vous devez copier la clé avant de l’enregistrer, car vous ne pourrez plus la copier ensuite. Vous pouvez uniquement révéler une clé secrète par défaut ou une clé générée par une révocation planifiée.
Pour révéler une clé secrète ou limitée en mode production et ajouter une note :
Remarque
Le lien « Clés API » s’ouvre ici en mode production.
- Dans le Dashboard des développeurs, sélectionnez l’onglet Clés API.
- Dans la liste Clés standard ou des Clés limitées, cliquez sur Révéler la clé de production au regard de la ligne correspondant à la clé que vous souhaitez révéler.
- Copiez la valeur de la clé en cliquant dessus.
- Enregistrez la valeur de la clé.
- Cliquez sur Masquer la clé de test.
- Cliquez sur le menu déroulant () à côté de la clé, puis sélectionnez Modifier la clé.
- Dans le champ Note, saisissez l’emplacement où vous avez enregistré la clé, puis cliquez sur Enregistrer.
- Si vous avez créé la clé avant que Stripe ne propose cette fonctionnalité, cliquez sur Masquer la clé de production.
Remarque
Les clés créées avant le lancement de cette fonctionnalité par Stripe ne sont pas automatiquement masquées lorsqu’elles sont révélées. Vous devez les masquer manuellement.
Limiter les clés secrètes ou limitées à une liste ou une plage d’adresses IP
Pour limiter les requêtes API utilisant une clé à une ou plusieurs adresses IP spécifiques ou à une plage d’adresses IP :
Plages d'adresses IP valides
Vous pouvez spécifier n’importe quelle plage CIDR valide. Par exemple, une plage valide pourrait être 100., spécifiée comme 100.. Toutes les adresses de la plage doivent commencer par 100..
- Ouvrez la page Clés API.
- Dans la liste Clés standard ou des Clés limitées, cliquez sur le menu déroulant () au regard de la ligne correspondant à la clé que vous souhaitez révéler, puis sélectionnez Gérer les restrictions des adresses IP.
- Cliquez sur Limiter l’utilisation à un ensemble d’adresses IP.
- Saisissez une adresse IP ou une plage d’adresses IP :
- Pour une adresse IP individuelle, renseignez-la dans le champ Adresse IP.
- Pour une plage d’adresses IP, entrez la plage en notation CIDR (Classless Inter-Domain Routing). Dans le champ Adresse IP, saisissez la première adresse de la plage. Dans le champ CIDR, entrez la taille du préfixe réseau.
- Vous pouvez également sélectionner l’onglet Gestion en bloc et saisir des adresses IP individuelles et des plages, séparées par des espaces. Les modifications apportées dans un onglet apparaissent dans l’autre onglet.
- Pour ajouter une autre adresse ou plage, cliquez sur + Ajouter.
- Cliquez sur Enregistrer.
Modifier le nom ou la note d’une clé API secrète ou limitée
Pour modifier le nom ou le texte de la note d’une clé secrète ou limitée :
- Ouvrez la page Clés API.
- Dans la ligne correspondant à la clé à modifier, cliquez sur le menu déroulant (), puis sélectionnez Modifier la clé.
- Si vous souhaitez modifier le nom de la clé, saisissez le nouveau nom dans le champ Nom de la clé.
- Si vous souhaitez modifier le texte de la note, saisissez le nouveau texte dans Note.
- Cliquez sur Enregistrer.
Protégez vos clés
N’importe qui peut utiliser votre clé API secrète en mode production pour effectuer un appel à l’API au nom de votre compte, par exemple pour créer un paiement ou procéder à un remboursement. Protégez vos clés en suivant les bonnes pratiques relatives aux clés API secrètes.