Clés API
Utilisez les clés API pour authentifier les 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 effectuer la rotation des 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 au total de quatre clés API : deux dans un bac à sable et deux en mode production :
- Clé secrète du bac à sable : Utilisez cette clé pour authentifier les requêtes sur votre serveur lorsque vous effectuez des tests dans un bac à sable. Par défaut, vous pouvez utiliser cette clé pour exécuter n’importe quelle requête d’API sans restriction. Réservez cette clé aux tests et au développement afin de vous assurer de ne pas modifier accidentellement vos clients réels ou vos paiements.
- Clé publique du bac à sable : Utilisez cette clé à des fins de test dans le code côté client de votre application Web ou mobile. Réservez cette clé aux tests et au développement afin de vous assurer de ne pas modifier accidentellement vos clients réels ou vos paiements.
- ** 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 utiliser cette clé pour effectuer n’importe quelle requête d’API sans restriction.
- ** Clé publique en mode production** : utilisez cette clé, lorsque vous êtes prêt à lancer votre application, dans le code côté client de votre application Web ou mobile.
Vos clés secrète et publique 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é à Stripe, nos exemples de code contiennent automatiquement vos clés API de test. Personne d’autre que vous ne peut voir ces valeurs. Si vous n’êtes pas connecté, nos exemples de code incluent 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 montre des exemples de clés API de test secrètes et publiables générées de manière aléatoire :
| Type | Valeur | Utilisation |
|---|---|---|
| Secrète | sk_ | Côté serveur : Doit être secret et stocké en toute sécurité dans le code côté serveur de votre application Web ou mobile (comme dans une variable d’environnement ou un système de gestion des identifiants) pour appeler les API Stripe. N’exposez pas cette clé sur un site Web et ne l’intégrez dans une application mobile. |
| Publiable | pk_ | Côté client : Peut être accessible au public dans le code côté client (comme checkout.js) de votre application Web ou mobile pour collecter les informations de paiement de manière sécurisée, comme avec Stripe Elements. Par défaut, Stripe Checkout collecte les informations de paiement de manière sécurisée. |
| Limitée | Une chaîne qui commence par rk_ | Microservices : Doit être secret et stocké en toute sécurité dans votre code de microservice pour appeler les API Stripe. N’exposez pas cette clé sur un site Web et ne l’intégrez pas dans une application mobile. |
Bac à sable ou mode production
Toutes les requêtes d’API Stripe s’effectuent dans le bac à sable ou en mode production. Utilisez un bac à sable pour accéder aux données de test et un mode production pour accéder aux données réelles du compte. Chaque mode possède son propre ensemble de clés API. Les objets d’un mode ne sont pas accessibles dans l’autre. Par exemple, un objet Product dans un bac à sable 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é secrète ou une clé API limitée en mode production. Si vous la perdez, vous ne pourrez pas la récupérer à partir du Dashboard. Dans ce cas, effectuez une rotation ou supprimez-la et créez-en une nouvelle.
| Type | Quand l’utiliser | Objets | Comment l’utiliser | Considérations |
|---|---|---|---|---|
| bacs à sable | Utilisez un bac à sable 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 d’API renvoient des objets simulés. Par exemple, vous pouvez récupérer et utiliser des objets de test account, payment, customer, charge, refund, transfer, balance et subscription. | Utilisez des cartes de crédit et des comptes de test. Vous ne pouvez pas accepter de modes de paiement réels ou travailler avec des comptes réels. | Identity n’effectue aucune vérification. De plus, les objets Account de Connect ne renvoient pas de champs sensibles. |
| mode production | Utilisez le mode production et ses clés API associées lorsque vous êtes prêt à lancer votre intégration et à accepter de l’argent réel. En mode production, les réseaux de cartes et les fournisseurs de paiement traitent les paiements. | Les appels d’API renvoient des objets réels. Par exemple, vous pouvez récupérer et utiliser de vrais objets account, payment, customer, charge, refund, transfer, balance et subscription. | Acceptez de véritables cartes de crédit et travaillez avec des comptes clients. Vous pouvez accepter des autorisations, frais et captures de paiement réels pour les cartes de crédit et les comptes. | Les flux de litiges sont plus nuancés et le processus de test est plus simple. De plus, certains modes de paiement ont un flux plus nuancé et nécessitent plus d’étapes. |
Faire pivoter une clé API
La rotation d’une clé la révoque et génère une clé de remplacement. Vous pouvez effectuer la rotation d’une clé immédiatement ou programmer une rotation à une date ultérieure. Effectuez la rotation d’une clé dans des scénarios tels que les exemples suivants :
- Si vous perdez une clé secrète ou une clé limitée en mode production, vous ne pouvez pas la récupérer à partir du Dashboard et vous devez la remplacer.
- Si une clé secrète ou limitée est compromise, 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 effectuez la rotation d’une clé API :
- Ouvrez la page clés API.
- Sur la ligne correspondant à la clé pour laquelle vous souhaitez effectuer la rotation, cliquez sur le menu de dépassement (), puis sélectionnez Rotation de la clé.
- Choisissez une date d’expiration dans le menu déroulant Expiration.
- Cliquez sur **Alterner la clé API **.
- La boîte de dialogue affiche la nouvelle valeur de la clé. Copiez la valeur en cliquant sur la clé.
- 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 Enregistrer.
Si vous avez sélectionné Maintenant pour le champ Expiration, nous supprimerons l’ancienne clé. Si vous avez sélectionné une autre durée, vous verrez le temps restant avant que 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 effectuez la rotation d’une clé publique, le nom de la clé de remplacement est toujours Publishable key. Lorsque vous effectuez la rotation d’une clé secrète, le nom de la clé de remplacement est toujours Secret key. Lorsque vous effectuez la rotation d’une clé limitée, le nom de la clé de remplacement est le même que celui de la clé qui a fait l’objet de la rotation. Vous pouvez renommer une clé secrète ou limitée en cliquant sur son menu de débordement et en sélectionnant Modifier la clé.
Afficher les journaux des requêtes d’API
Pour ouvrir les journaux des requêtes d’API, cliquez sur le menu de débordement () de n’importe quelle clé, puis sélectionnez **Afficher les journaux des requêtes **. L’ouverture des journaux vous redirige au Dashboard Stripe principal.
Clés secrètes et limitées
Utilisez le Dashboard pour créer, supprimer, révéler 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 à votre adresse courriel ou par message texte. (Le courriel ou le message texte 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 valeur en cliquant sur la clé.
- 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 précisez.
Pour créer une clé API limitée :
- Ouvrez la page clés API.
- Vous pouvez créer une clé limitée à partir de zéro ou commencer par cloner 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 de débordement () et sélectionnez Dupliquer la clé en regard de la clé à cloner. Dans ce cas, la valeur par défaut de chaque autorisation correspond à sa valeur dans la clé clonée.
- Dans le champ Nom de la clé, entrez un nom. Si vous avez cloné une clé existante, le nom par défaut est le nom de la clé clonée.
- Pour chaque ressource à laquelle la nouvelle clé doit accéder, sélectionnez l’autorisation à accorder pour cette clé. Si vous utilisez Connect, vous pouvez également sélectionner l’autorisation à accorder pour cette clé lors de l’accès aux comptes connectés. Les autorisations disponibles sont Aucune, Lecture et Écriture.
- Cliquez sur Créer une clé.
- Stripe envoie un code de vérification à votre adresse courriel ou par message texte. (Le courriel ou le message texte 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 valeur en cliquant sur la clé.
- 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é, tout code qui utilise cette clé ne peut plus effectuer d’appels à l’API. Après avoir supprimé une clé, créez-en une nouvelle et mettez à jour le code pour l’utiliser.
Remarques
Vous ne pouvez pas supprimer une clé publique.
Pour supprimer une clé :
- Dans le Dashboard des développeurs, sélectionnez l’onglet Clés API.
- Recherchez la clé que vous souhaitez supprimer dans la liste Clés standard ou Clés limitées. Cliquez sur le menu de débordement () en regard de 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 boîte de dialogue Supprimer la clé API. Sinon, cliquez sur Annuler.
Révéler une clé API secrète dans un bac à sable
Avec les bacs à sable, 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 bac à sable :
- Dans le Dashboard des développeurs, sélectionnez l’onglet Clés API.
- Dans la liste Clés standard, cliquez sur Révéler la clé de test sur la ligne Clé secrète.
- Copiez la valeur de la clé en cliquant sur celle-ci.
- Enregistrez la valeur de la clé.
- Cliquez sur Masquer la clé test.
Révéler une clé API secrète ou limitée pour le mode production
Pour des raisons de sécurité, Stripe n’affiche les clés API secrètes ou limitées qu’une seule fois en mode production. Enregistrez la clé dans un emplacement sécurisé, là où vous ne la perdrez pas. Pour vous aider à vous souvenir de l’endroit où vous la conservez, vous pouvez ajouter une note à ce propos dans le Dashboard. Si vous perdez la clé, vous pouvez effectuer une rotation ou la supprimer, puis en créer une autre.
Vous ne pouvez pas révéler une clé secrète que vous avez généré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 pas la copier ultérieurement. Vous pouvez uniquement révéler une clé secrète par défaut ou une clé générée par une rotation planifiée.
Pour révéler une clé secrète ou limitée en mode production et y joindre une note :
Remarques
Le lien « Clés API » s’ouvre ici en mode production.
- Dans le Dashboard des développeurs, sélectionnez l’onglet Clés API.
- Cliquez sur Révéler la clé de production dans la liste Clés standard ou Clés limitées en regard de la clé que vous souhaitez révéler.
- Copiez la valeur de la clé en cliquant sur celle-ci.
- Enregistrez la valeur de la clé.
- Cliquez sur Masquer la clé test.
- Cliquez sur le menu de débordement () en regard de la clé, puis sélectionnez Modifier la clé.
- Dans le champ Remarque, saisissez l’emplacement où vous avez enregistré la clé, puis cliquez sur Enregistrer.
- Si vous avez créé la clé avant que Stripe n’introduise cette fonctionnalité, cliquez sur Masquer la clé de production.
Remarques
Les clés que vous avez créées avant l’application de cette fonctionnalité ne seront pas automatiquement masquées. Vous devez les masquer.
Limiter les clés secrètes ou limitée à 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 préciser une plage CIDR valide. Par exemple, une plage valide peut être 100. précisée sous la forme de 100.. Toutes les adresses de la plage doivent commencer par 100..
- Ouvrez la page clés API.
- Cliquez sur le menu de débordement () dans la liste Clés standard ou Clés limitées en regard de la clé que vous souhaitez révéler, puis sélectionnez Gérer les restrictions des adresses IP.
- Cliquer sur Limiter l’utilisation à un groupe d’adresses IP.
- Entrez une adresse IP ou une plage d’adresses IP :
- Pour une adresse IP individuelle, entrez-la dans le champ Adresse IP.
- Pour une plage d’adresses IP, entrez la plage au format Classless Inter-Domain Routing (CIDR). Dans le cham Adresse IP, entrez la première adresse dans la plage. Dans le champ CIDR, entrez la taille du préfixe du réseau.
- Vous pouvez également sélectionner l’onglet Gestion groupée et saisir des adresses IP et des plages individuelles, séparées par des espaces. Les modifications apportées dans un onglet sont affichées 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.
- Cliquez sur le menu de débordement () en regard de la clé que vous souhaitez modifier, 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.
Conservez vos clés en sécurité
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 effectuer un remboursement. Protégez vos clés en suivant les bonnes pratiques en matière de clés API secrètes.