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 pour développeurs pour créer, révéler, supprimer et effectuer la rotation des 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 environnement de test	Authentifiez les requêtes sur votre serveur lors des tests en environnement de test. Par défaut, cette clé permet d’effectuer n’importe quelle requête API sans restriction. Réservez-la aux phases de test et de développement afin de vous assurer de ne pas modifier accidentellement vos clients ou vos paiements en mode production.
Environnement de test d’une clé publiable	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 en mode production	Authentifiez 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 en mode production	Lorsque vous êtes prêt à lancer votre application, utilisez cette clé 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 des 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 présente des exemples de clés secrètes et publiques générées de manière aléatoire :

Type	Valeur	Utilisation
Secrète	`sk_test_VePHdqKTYQjKNInc7u56JBrQ`	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_test_oKhSR5nslBRnBZpjO6KuzZeX`	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_test_`	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.

Protéger vos clés

Toute personne disposant de votre clé secrète en mode production peut effectuer des appels à l’API au nom de votre compte, par exemple pour créer un débit ou effectuer un remboursement. Suivez ces bonnes pratiques pour protéger vos clés API secrètes.

Environnement de test ou mode production

Toutes les requêtes vers l’API Stripe s’effectuent soit en environnement de test, soit en mode production. L’environnement de test permet d’accéder aux données de test, tandis que le mode production permet d’accéder aux données réelles du compte. Chaque mode dispose de son propre ensemble de clés API, et les objets d’un mode ne sont pas accessibles dans l’autre. Par exemple, un objet produit en environnement de test ne peut pas être utilisé pour 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 depuis le Dashboard. Dans ce cas, effectuez une rotation ou supprimez-la, puis 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.

Clés API d’organisation

Si vous avez plusieurs comptes professionnels Stripe dans une organisation, vous pouvez configurer une seule clé API au niveau de l’organisation. Les clés API au niveau de l’organisation offrent les fonctionnalités suivantes :

Accéder à n’importe quel compte. Utilisez les clés API de l’organisation pour accéder aux ressources de n’importe quel compte de l’organisation.

Autorisations granulaires. Limitez les clés API de l’organisation afin d’accorder des autorisations en lecture ou en écriture uniquement pour des ressources spécifiques.
Gestion centralisée. Créez et gérez les clés API de l’organisation dans l’onglet Clés API du Dashboard de votre organisation.

Comportement

Les clés API d’organisation se comportent différemment des clés API au niveau du compte, notamment :

Elles n’ont pas de clé publiable. Traitez toutes les clés API d’organisation comme des clés secrètes.
Elles ont tous le même préfixe sk_org, quel que soit leur niveau d’autorisation.
Toutes les requêtes API effectuées à l’aide d’une clé API d’organisation doivent inclure l’en-tête Stripe-Context afin d’identifier le compte concerné.
Toutes les requêtes API effectuées à l’aide d’une clé d’API d’organisation doivent inclure l’en-tête Stripe-Version afin de garantir la cohérence et la prévisibilité des intégrations de votre organisation.

Utiliser les clés API d’organisation

Lorsque vous utilisez une clé API d’organisation, vous devez également :

Spécifiez une version de l’API en incluant un en-tête Stripe-Version. Lors de l’utilisation d’un SDK Stripe, le SDK définit automatiquement la version de l’API.
Identifiez le compte concerné par la requête API en incluant l’en-tête Stripe-Context.

Par exemple, avec la structure d’organisation suivante :

Organization (org_6SD3oI0eSQemPzdmaGLJ5j6)
  ├── Platform account  (acct_1R3fqDP6919yCiFv)
  |   └── Connected account (acct_1032D82eZvKYlo2C)
  └── Standalone account (acct_1aTnTtAAB0hHJ26p)

Vous pouvez utiliser la clé API d’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é à 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 un compte connecté, utilisez un chemin qui identifie à la fois la plateforme et le compte connecté, en respectant le format acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C.

Vous devez spécifier le compte concerné à l’aide du contexte et de la version de l’API, et ce, 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 des paiements. Vous pouvez utiliser la clé API de votre organisation pour créer un PaymentIntent pour n’importe quel compte de l’organisation, mais vous devez utiliser les clés publiables existantes propres à chaque compte pour les opérations côté client.

Clés secrètes et limitées

Utilisez le Dashboard pour créer, révéler, modifier, supprimer et effectuer la rotation des clés API 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 définissez.

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 envoie par e-mail ou par SMS. Si la boîte de dialogue ne se poursuit 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 nouvelle clé limitée, cliquez sur Créer une clé limitée. Par défaut, toutes les autorisations sont définies sur Aucune.
- Pour cloner une clé existante, cliquez sur le menu de débordement (), puis sélectionnez Dupliquer la clé pour la clé à cloner. La valeur par défaut de chaque autorisation correspond à celle 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 correspond à celui de la clé dupliquée.
Pour chaque ressource à laquelle la nouvelle clé doit accéder, sélectionnez l’autorisation appropriée : Aucune, Lecture ou Écriture. Si vous utilisez Connect, vous pouvez également définir l’autorisation permettant à cette clé d’accéder 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 envoie par e-mail ou par SMS. Si la boîte de dialogue ne se poursuit 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é.

Révéler une clé API

Vous pouvez révéler une clé API secrète ou une clé API limitée dans un environnement de test ou en mode production.

Pour des raisons de sécurité, Stripe n’affiche une clé API secrète qu’une seule fois en mode production. Conservez-la dans un emplacement sûr. Pour vous rappeler où elle est stockée, vous pouvez ajouter une note à la clé dans le Dashboard. Si vous perdez la clé, vous pouvez effectuer une rotation ou la supprimer, puis en créer une nouvelle.

Révéler les clés secrètes 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é API secrète dans un environnement de test

Dans 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. Vous pouvez révéler la clé API secrète autant de fois que nécessaire.
Cliquez sur la valeur de la clé pour la copier.
Enregistrez la valeur de la clé.
Cliquez sur Masquer la clé de test.

Pour révéler 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 Révéler la clé en mode production 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é de test.
Cliquez sur le menu de débordement (), 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 créées avant l’introduction de cette fonctionnalité par Stripe ne sont pas automatiquement masquées lorsqu’elles sont révélées. Vous devez les masquer manuellement en cliquant sur Masquer la clé en mode production.

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 spécifiques.

Les adresses IP doivent utiliser le protocole IPv4, et vous pouvez spécifier toute plage CIDR valide. Par exemple, la plage 100.10.38.0 - 100.10.38.255 peut être définie comme 100.10.38.0/24. Toutes les adresses IP de la plage doivent commencer par 100.10.38.

Dans l’onglet Clés API, dans la liste Clés standard ou Clés limitées, cliquez sur le menu de débordement () de la clé que vous souhaitez révéler.
Sélectionnez Gérer les restrictions d’adresses IP > Limiter l’utilisation à un ensemble 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 dans le champ Adresse IP (en notation CIDR, Classless Inter-Domain Routing), puis indiquez la taille du préfixe réseau dans le champ CIDR.
Vous pouvez également saisir des adresses IP et des plages individuelles (séparées par des espaces) dans l’onglet Gérer en masse. Les modifications apportées dans un onglet s’appliquent automatiquement à l’autre.
Pour ajouter une autre adresse IP ou plage, 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 de débordement () de la clé que vous souhaitez modifier.
Sélectionnez Modifier la clé.
Effectuez les actions suivantes :
- 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 utilisait la clé supprimée. Tout code reposant sur cette clé ne pourra plus effectuer d’appels à l’API.

Remarque

Vous ne pouvez pas supprimer une clé publiable.

Dans l’onglet Clés API, dans la liste Clés standard ou Clés limitées, cliquez sur le menu de débordement () en regard de 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 la supprimer, cliquez sur Annuler.

Modifier une clé API

La rotation d’une clé API la révoque et génère une clé de remplacement immédiatement utilisable. Vous pouvez également planifier la rotation d’une clé API à une date ultérieure. La clé de remplacement est nommée comme suit :

Le nom de la clé publiable de remplacement est toujours Publishable key.
Le nom de la clé secrète de remplacement est toujours Secret key.
Le nom de la clé limitée de remplacement est identique à celui de la clé faisant l’objet de la rotation.

Vous pouvez renommer une clé API secrète ou limitée en modifiant la clé.

Effectuer 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 que vous ne pouvez pas la récupérer depuis le Dashboard.
Si une clé API secrète ou limitée est compromise et que vous devez la révoquer afin de bloquer toute requête API potentiellement malveillante.
Si votre politique impose une rotation des clés à intervalles réguliers.

Rotation d’une clé API

Dans l’onglet Clés API, cliquez sur le menu de débordement () de la clé que vous souhaitez faire tourner.
Sélectionnez Rotation de la clé.
Sélectionnez une date d’expiration dans la liste déroulante Expiration. Si vous choisissez Maintenant, l’ancienne clé est supprimée. Si vous indiquez une heure, le temps restant avant l’expiration de la clé s’affiche sous le nom de la clé.
Cliquez sur Rotation de 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 Terminé.

Afficher les logs des requêtes API

Pour ouvrir les logs des requêtes API, cliquez sur le menu de débordement () associé à une clé, puis sélectionnez Afficher les logs des requêtes. L’ouverture des logs vous redirige vers le Dashboard Stripe.