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, afficher, supprimer et faire une rotation les clés API. Vous pouvez accéder à vos clés API v1 dans l’onglet Clés API.
Types de clés
Par défaut, tous les comptes disposent au total de quatre clés API :
| Type | Description |
|---|---|
| Clé secrète en mode bac à sable | Authentifiez les requêtes sur votre serveur lorsque vous effectuez des tests dans un bac à sable. Par défaut, vous pouvez utiliser cette clé pour effectuer n’importe quelle requête API sans restriction. Réservez cette clé aux tests et au développement afin de vous assurer de ne pas modifier accidentellement vos clients ou paiements en mode production |
| Clé publiable en mode bac à sable | Testez les requêtes dans le code côté client de votre application Web ou mobile. Réservez cette clé pour les tests et le développement afin de vous assurer de ne pas modifier accidentellement vos clients ou vos paiements en mode production. |
| Clé secrète mode production | 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é publiable du 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ètes et publiables 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.
Si vous êtes connecté à Stripe, notre documentation remplit les exemples de code avec vos clés API test. Vous seul pouvez voir ces valeurs. Si vous n’êtes pas connecté, nos exemples de code incluent des clés API générées aléatoirement que vous pouvez remplacer par vos clés test. Vous pouvez également vous connecter pour voir les exemples de code remplis avec vos clés API test.
Exemples de clés API
Le tableau suivant montre des exemples de clés 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 recueillir de manière sécuritaire les informations de paiement, comme avec Stripe Elements). Par défaut, Stripe Checkout recueille de manière sécuritaire les informations de paiement. |
| 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. |
Protéger vos clés
N’importe qui peut utiliser votre clé secrète en mode production pour effectuer un appel à l’API au nom de votre compte, par exemple pour effectuer un paiement ou un remboursement. Suivez ces bonnes pratiques pour protéger vos clés API secrètes.
Bac à sable ou mode production
Toutes les requêtes à l’API Stripe sont traitées soit en mode sandbox, soit en mode live. Vous pouvez utiliser un bac à sable pour accéder aux données de test et le mode production pour accéder aux données réelles du compte. Chaque mode dispose de son propre ensemble de clés API, et les éléments d’un mode ne sont pas accessibles depuis l’autre. Par exemple, un élément de produit du bac à sable ne peut pas faire partie d’un paiement en mode production.
Accès aux clés API en mode production
En mode production, vous ne pouvez révéler une clé API secrète ou limitée qu’une seule fois. Si vous la perdez, vous ne pouvez pas la récupérer à partir du Dashboard. Dans ce cas, faites la rotation de la clé ou supprimez-la, puis 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. |
Clés API de l’organisation
Si vous avez plusieurs comptes d’entreprise Stripe au sein d’une organisation, vous pourrez configurer une seule clé API au niveau de l’organisation. Les clés API au niveau de l’organisation offrent la fonctionnalité suivante :
- Accédez à n’importe quel compte : utilisez les clés API de l’organisation pour accéder aux ressources de n’importe quel compte au sein de l’organisation.
- Autorisations granulaires : restreignez les clés API de l’organisation afin d’accorder des autorisations de lecture ou d’écriture uniquement à des ressources particulières.
- Gestion centralisée : créez et gérez les clés API de votre organisation dans l’onglet Clés API du Dashboard de votre organisation.
Comportement
Les clés API de l’organisation se comportent différemment des clés API au niveau du compte, y compris ce qui suit :
- Elles n’ont pas de clé publique. Traitez toutes les clés API de l’organisation comme des clés secrètes.
- Elles ont toutes le même préfixe
sk_, quel que soit leur niveau d’autorisation.org - Toutes les requêtes d’API effectuées à l’aide d’une clé API de l’organisation doivent inclure l’en-tête
Stripe-Contextafin d’identifier le compte concerné. - Toutes les requêtes d’API effectuées à l’aide d’une clé d’API d’organisation doivent inclure l’en-tête
Stripe-Versionafin de garantir la cohérence et la prévisibilité des intégrations de votre organisation.
Utiliser les clés API de l’organisation
Lorsque vous utilisez une clé API d’organisation, vous devez également effectuer ce qui suit :
- Précisez une version d’API en ajoutant un en-tête
Stripe-Version. Lors de l’utilisation d’une trousse SDK Stripe, la trousse SDK définit automatiquement la version de l’API. - Identifiez le compte concerné par la requête d’API en ajoutant l’en-tête
Stripe-Context.
Prenons l’exemple de la structure organisationnelle suivante :
Organization (org_6SD3oI0eSQemPzdmaGLJ5j6) ├── Platform account (acct_1R3fqDP6919yCiFv) | └── Connected account (acct_1032D82eZvKYlo2C) └── Standalone account (acct_1aTnTtAAB0hHJ26p)
Vous pouvez utiliser la clé API de l’organisation pour accéder au solde du compte autonome. Vous pouvez également utiliser la même clé pour effectuer le même appel pour le compte connecté de la plateforme.
Dans l’exemple de code précédent, remplacez {{CONTEXT}} par la valeur appropriée :
- Pour le compte autonome, utilisez
acct_.1aTnTtAAB0hHJ26p - Pour le compte connecté, utilisez un chemin d’accès qui identifie à la fois la plateforme et le compte connecté, en suivant le format
acct_.1R3fqDP6919yCiFv/acct_ 1032D82eZvKYlo2C
Vous devez spécifier le compte concerné à l’aide du contexte et de la version de l’API dans toute requête d’API utilisant une clé d’organisation.
Les organisations ne disposent pas de clés API publiables, car elles ne peuvent pas accepter de paiements. Vous pouvez utiliser la clé API de votre organisation pour créer un PaymentIntent pour n’importe quel compte de votre organisation, mais vous devez utiliser les clés publiables existantes particulières au compte pour les opérations côté client.
Clés secrètes et limitées
Utilisez le Dashboard pour créer, afficher, modifier, supprimer et faire la rotation des clés secrètes et limitées.
Créer une clé API
vous pouvez créer une clé API secrète ou une clé API limitée. une clé api limitée n’autorise que le niveau d’accès que vous précisez.
Pour créer une clé API secrète
- Dans l’onglet Clés API, cliquez sur Créer une clé secrète.
- Dans la boîte de dialogue, saisissez le code de vérification que Stripe vous a envoyé par courriel ou par SMS. Si la boîte de dialogue ne s’ouvre pas automatiquement, cliquez sur Continuer.
- Saisissez un nom dans le champ Nom de la clé, puis cliquez sur Créer.
- Cliquez sur la valeur de la clé pour la copier.
- 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é, puis cliquez sur Terminé.
Pour créer une clé API limitée
- Dans l’onglet Clés API, effectuez l’une des actions suivantes :
- Pour créer une clé limitée, cliquez sur Créer une clé limitée. La valeur par défaut pour toutes les autorisations est Aucune.
- Pour cloner une clé existante, cliquez sur le menu déroulant (), puis sélectionnez Dupliquer la clé pour la clé que vous souhaitez cloner. La valeur par défaut pour chaque autorisation est la valeur de la clé clonée.
- Saisissez un nom dans le champ Nom de la clé. Si vous avez cloné une clé existante, le nom par défaut est le nom de la clé clonée.
- Pour chaque ressource à laquelle vous souhaitez que la nouvelle clé ait accès, sélectionnez l’autorisation appropriée : Aucune, Lire ou Écrire. Si vous utilisez Connect, vous pouvez également sélectionner l’autorisation à accorder à cette clé lors de l’accès aux comptes connectés.
- Cliquez sur Créer une clé.
- Dans la boîte de dialogue, saisissez le code de vérification que Stripe vous a envoyé par courriel ou par SMS. Si la boîte de dialogue ne s’ouvre pas automatiquement, cliquez sur Continuer.
- Cliquez sur la valeur de la clé pour la copier.
- 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é, puis cliquez sur Terminé.
Afficher une clé API
Vous pouvez afficher une clé API secrète ou une clé API limitée dans un bac à sable ou en mode production.
En mode production, Stripe ne vous montre la clé API qu’une seule fois (pour des raisons de sécurité). Conservez la clé dans un endroit où vous ne risquez pas de la perdre. Pour vous rappeler où vous l’avez sauvegardée, vous pouvez ajouter une note sur la clé dans le Dashboard. Si vous perdez la clé, vous pouvez la remplacer ou la supprimer et en créer une autre.
Afficher les clés secrètes du 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 afficher une clé API secrète dans un bac à sable
- Dans l’onglet Clés API, dans la liste Clés standard, cliquez sur Afficher la clé de test dans la colonne Clé secrète. Vous pouvez afficher la clé API secrète autant de fois que vous le souhaitez.
- Cliquez sur la valeur de la clé pour la copier.
- Enregistrez la valeur de la clé.
- Cliquez sur Masquer la clé test.
Pour afficher une clé API secrète ou limitée en mode production
- Dans l’onglet Clés API en mode production, dans la liste Clés standard ou Clés limitées, cliquez sur Afficher la clé active pour la clé que vous souhaitez afficher.
- Cliquez sur la valeur de la clé pour la copier.
- Enregistrez la valeur de la clé.
- Cliquez sur Masquer la clé test.
- Cliquez sur le menu déroulant (), puis sélectionnez Modifier la clé pour la clé à laquelle vous souhaitez ajouter une note.
- Dans le champ Note, saisissez l’emplacement où vous avez enregistré la clé, puis cliquez sur Enregistrer.
Remarque
Les clés que vous avez créées avant l’application de cette fonctionnalité par Stripe ne seront pas automatiquement masquées lorsqu’elles seront activées. Vous devez les masquer manuellement en cliquant sur Masquer la clé active.
Limiter une clé API à certaines adresses IP
Vous pouvez limiter une clé API secrète ou une clé API limitée à une plage d’adresses IP ou à une ou plusieurs adresses IP particulières.
Les adresses IP doivent utiliser le protocole IPv4, et vous pouvez préciser n’importe quelle plage d’adresses CIDR valide. Par exemple, une plage d’adresses valide pourrait être 100., et vous pouvez la préciser comme 100.. Toutes les adresses IP de la plage doivent commencer par 100..
Dans l’onglet Clés API, dans la liste Clés standard ou Clés limitées, cliquez sur le menu déroulant () correspondant à la clé que vous souhaitez afficher.
Sélectionnez Gérer les restrictions des adresses IP > Limiter l’utilisation à un groupe d’adresses IP.
Effectuez l’une des actions suivantes :
- Saisissez une adresse IP individuelle dans le champ Adresse IP.
- Pour une plage d’adresses IP, saisissez la première adresse de la plage (en utilisant la notation CIDR (Classless Inter-Domain Routing)) dans le champ Adresse IP. Saisissez la taille du préfixe réseau dans le champ CIDR.
Vous pouvez également saisir des adresses IP individuelles et des plages d’adresses (séparées par des espaces) dans l’onglet Gestion groupée. Les modifications apportées dans un onglet sont affichées dans l’autre onglet.
Pour ajouter une autre adresse IP ou plage d’adresses, cliquez sur + Ajouter.
Cliquez sur Enregistrer.
Modifier le nom ou la note d’une clé API
- Dans l’onglet Clés API, cliquez sur le menu déroulant () correspondant à la clé que vous souhaitez modifier.
- Sélectionnez Modifier la clé.
- Procédez comme suit :
- Pour modifier le nom, saisissez un nouveau nom dans le champ Nom de la clé.
- Pour modifier le texte de la note, saisissez le nouveau texte dans le champ Note.
- Cliquez sur Enregistrer.
Supprimer une clé API
Si vous supprimez une clé API secrète ou une clé API limitée, vous devez en créer une nouvelle et mettre à jour tout code qui utilise la clé supprimée. Tout code qui utilise la clé supprimée ne peut plus effectuer des appels à l’API.
Remarque
Vous ne pouvez pas supprimer une clé publique.
- Dans l’onglet Clés API, dans la liste Clés standard ou Clés limitées, cliquez sur le menu déroulant () correspondant à la clé que vous souhaitez supprimer.
- Sélectionnez Supprimer la clé.
- Dans la boîte de dialogue, cliquez sur Supprimer la clé. Si vous ne souhaitez plus supprimer la clé, cliquez sur Annuler.
Faire pivoter une clé API
Faire la rotation d’une clé API la révoque et génère une clé de remplacement prête à être utilisée immédiatement. Vous pouvez également programmer une rotation de clé API à des intervalles réguliers. La clé de remplacement est nommée comme suit :
- Le nom de la clé publiable de remplacement est toujours
Clé publiable. - Le nom de la clé secrète de remplacement est toujours
Clé secrète. - Le nom de la clé limitée de remplacement est identique à celui de la clé en rotation.
Vous pouvez renommer une clé API secrète ou limitée en modifiant la clé.
Faites la rotation d’une clé API dans les scénarios suivants :
- Si vous perdez une clé API secrète ou limitée en mode production et vous ne pouvez pas la récupérer depuis le Dashboard.
- Si une clé API secrète ou limitée est compromise, et vous devez la révoquer pour bloquer toute requête à l’API potentiellement malveillante susceptible d’utiliser cette clé.
- Si votre politique exige la rotation des clés à intervalles réguliers.
Faire la rotation (changer) d’une clé API
- Dans l’onglet Clés API, cliquez sur le menu déroulant () correspondant à la clé dont vous souhaitez faire la rotation.
- Sélectionnez Faire la rotation de la clé (changer la clé).
- Sélectionnez une date d’expiration dans le menu déroulant Expiration. Si vous choisissez Maintenant, l’ancienne clé sera supprimée. Si vous précisez une heure, le temps restant avant l’expiration de la clé s’affichera sous le nom de la clé.
- Cliquez sur **Alterner la clé API **.
- Cliquez sur la valeur de la clé pour la copier.
- 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é, puis cliquez sur Enregistrer, ou sur Terminé.
Consulter les journaux des requêtes à l’API
Pour ouvrir les journaux des requêtes à l’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 vers le Dashboard Stripe.