# Bonnes pratiques en matière de gestion des clés API secrètes

Découvrez comment gérer vos clés API secrètes en toute sécurité et comment réagir rapidement en cas d’exposition ou de compromission.

Les clés API secrètes constituent des identifiants de compte, comparables à un nom d’utilisateur et un mot de passe. Contrairement aux clés publiques, qui peuvent être intégrées en toute sécurité dans des pages web ou des applications, les clés secrètes doivent impérativement rester dans votre environnement serveur. Si une personne non autorisée obtient votre clé API secrète, elle peut effectuer des paiements frauduleux, accéder aux données de vos clients ou perturber votre intégration.

Ce guide présente des méthodes spécifiques pour protéger les clés dans votre environnement serveur. Pour obtenir un aperçu des différents types de clés pris en charge par Stripe, consultez la page [Clés API](https://docs.stripe.com/keys.md).

## Protéger les clés API secrètes

Vous devez gérer et stocker vos clés API secrètes de manière sécurisée à chaque étape du développement afin de les protéger contre toute exposition ou compromission.

- **Ne placez jamais de clés API secrètes dans le code source** : des acteurs malveillants analysent en permanence les dépôts publics à la recherche de clés API Stripe. Même les dépôts privés peuvent être exposés via des environnements de développement.
  - Utilisez les outils de gestion des clés secrètes de votre plateforme (comme un coffre-fort secret) ou des variables d’environnement pour fournir les clés API à votre code d’intégration.
  - Auditez régulièrement votre code source, vos fichiers de configuration et vos pipelines CI/CD afin d’identifier toute clé sensible, notamment en recherchant les préfixes `sk_live_` et `rk_live_`. Si vous découvrez une clé sensible, considérez qu’elle a été [exposée et compromise](https://docs.stripe.com/keys-best-practices.md#handling-compromised-keys).
  - Utilisez un hook pre-commit dans votre système de gestion de versions afin de bloquer automatiquement tout commit contenant des chaînes correspondant à ces modèles.
  - Les extraits de code de la documentation Stripe incluent parfois des clés à titre d’illustration uniquement. N’utilisez pas de vraies clés dans votre code.
- **N’intégrez jamais de clés API secrètes dans vos applications :** des acteurs malveillants peuvent analyser ou désassembler une application afin d’y rechercher des clés intégrées. Pour les usages côté client - tels que les outils client, les SDK ou les applications mobiles - utilisez des [clés publiques](https://docs.stripe.com/keys.md#obtain-api-keys) à la place.
- **Appliquez le principe du moindre privilège :** les personnes et les systèmes ne doivent disposer que des autorisations *strictement nécessaires à l’exécution de leurs tâches*.
  - Définissez une politique claire précisant quels membres de l’équipe sont autorisés à créer, modifier ou consulter des clés API secrètes. Limitez l’accès aux seules personnes qui en ont besoin et vérifiez régulièrement les autorisations associées aux clés.
  - Maintenez une documentation à jour sur la gestion des clés API secrètes au sein de votre organisation. Organisez régulièrement des sessions de formation afin de renforcer l’adoption des bonnes pratiques.
- **Manipulez les clés API secrètes avec la plus grande prudence :** lorsque vous créez une clé API secrète dans le Dashboard Stripe, elle ne s’affiche qu’une seule fois. Stockez-la immédiatement dans l’outil sécurisé de gestion des informations sensibles de votre plateforme ou dans une variable d’environnement, et ne la conservez nulle part ailleurs.
  - Partagez vos clés API secrètes uniquement via les outils sécurisés de gestion des informations sensibles de votre plateforme - et non par e-mail, message instantané ou ticket d’assistance. **Stripe ne vous demandera jamais votre clé API secrète.**
  - Utilisez des [clés API restreintes](https://docs.stripe.com/keys-best-practices.md#limit-access), dotées d’autorisations limitées, plutôt que des clés API secrètes sans restriction.
- **Renouvelez régulièrement vos clés API secrètes :** définissez et testez un processus clair pour le [renouvellement de vos clés API Stripe](https://docs.stripe.com/keys.md#rolling-keys). Un renouvellement périodique vous permet de vérifier où chaque clé est utilisée et de vous assurer que votre équipe peut la remplacer rapidement si nécessaire. Formalisez un plan de secours afin que, en cas d’exposition ou de compromission d’une clé, votre équipe puisse réagir avec un impact minimal sur votre activité.
- **Auditez les logs des requêtes API afin de détecter toute activité suspecte :** examinez ou surveillez régulièrement les [logs des requêtes](https://docs.stripe.com/development/dashboard/request-logs.md) API afin d’identifier de manière proactive toute utilisation abusive de clés API. Assurez-vous que vos développeurs n’utilisent pas de clés en mode production lorsqu’une clé *d’environnement de test* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) est appropriée. Consultez la rubrique [Environnement de test versus mode production](https://docs.stripe.com/keys.md#test-live-modes).

## Stocker les clés API de manière sécurisée

N’intégrez pas de clés API limitées ou secrètes dans votre code, même dans du code qui reste sur vos serveurs. Des personnes malveillantes analysent continuellement les bases de code publiques pour trouver des clés API accidentellement exposées. Si vos développeurs laissent du code contenant des clés dans leurs environnements de développement, toute compromission d’un développeur peut entraîner l’exposition de ces clés.

Certains exemples de code Stripe incluent des clés d’environnement de test pour faciliter leur exécution immédiate. Si vous copiez un exemple de code, supprimez ces clés et utilisez un coffre-fort de secrets ou des variables d’environnement pour les stocker.

### Utiliser un coffre-fort de secrets

Pour éviter que vos développeurs n’interagissent régulièrement avec des clés API sensibles, utilisez un *coffre-fort de secrets*. Si vous stockez une clé API Stripe dans un coffre-fort de secrets, votre code peut faire référence à une clé API uniquement par son nom ou une référence. Le secret lui-même n’apparaît jamais dans votre code. Utilisez les fonctionnalités de permissions de votre plateforme d’hébergement pour autoriser l’accès seulement aux applications qui en ont besoin.

[Cet article de blog](https://stripe.dev/blog/securing-stripe-api-keys-aws-automatic-rotation) présente une façon de stocker et d’utiliser des secrets chez un fournisseur de services cloud. D’autres fournisseurs de services cloud et d’hébergement proposent des fonctionnalités similaires.

### Définir une clé API comme variable d’environnement

Si votre plateforme d’hébergement ne propose pas de coffre-fort de secrets, fournissez les clés à votre application via des variables d’environnement. Certaines plateformes permettent de marquer des variables d’environnement comme *sensibles* afin qu’elles ne soient plus visibles après leur définition. Vos applications peuvent toujours utiliser ces variables sensibles, mais elles ne peuvent pas être dérobées depuis votre navigateur web.

Lorsque vous exécutez des exemples de code de Stripe, définissez une variable temporaire pour votre session de terminal en cours. La variable d’environnement est supprimée lorsque vous fermez le terminal.

#### Mac/Linux

```bash
export STRIPE_API_KEY=sk_test_BQokikJOvBiI2HlWgH4olfQ2
```

### Utiliser la clé API dans votre code

Au lieu d’intégrer une clé codée en dur, votre code fait référence aux clés API par les noms des variables d’environnement.

#### Ruby

```ruby
client = Stripe::StripeClient.new(ENV["STRIPE_API_KEY"])
```

Si vous placez des clés API Stripe dans des variables d’environnement, veillez à ne pas les exposer à vos utilisateurs. Par exemple, n’affichez pas les variables d’environnement sur les pages d’erreur et ne rendez pas les modes de diagnostic accessibles au public.

## Personnaliser l’accès à l’API avec des clés API limitées

Au lieu d’utiliser des clés API secrètes offrant un accès étendu, créez des [clés API restreintes](https://docs.stripe.com/keys/restricted-api-keys.md) afin d’attribuer des autorisations spécifiques aux composants de vos applications. Par exemple, vous pouvez limiter votre système de facturation à la gestion des factures, exclusivement.

Les clés API restreintes vous permettent de limiter l’impact potentiel d’une compromission. Par exemple, si vous devez fournir une clé API Stripe à un tiers chargé du suivi des litiges, vous pouvez créer une clé API restreinte accordant un accès en lecture seule aux ressources liées aux litiges dans votre compte Stripe, tout en bloquant tout autre accès. Si ce tiers était compromis, un attaquant qui s’emparerait de votre clé API restreinte ne pourrait effectuer que ces appels à l’API spécifiques.

## Limiter les adresses IP pouvant envoyer des requêtes API

Si votre service envoie des requêtes API depuis des adresses IP fixes, vous pouvez restreindre vos clés API secrètes ou restreintes à ces adresses. Par exemple, si votre plateforme propose une passerelle NAT dédiée ou un autre mécanisme permettant de réserver une adresse IP ou une plage d’adresses, vous pouvez configurer Stripe pour bloquer toute requête API effectuée avec vos clés depuis une autre provenance.

Pour savoir comment restreindre une clé à une ou plusieurs adresses IP, consultez la rubrique [Limiter les clés secrètes ou restreintes à des adresses IP spécifiques](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address).

## Gérer les clés API compromises

Si une clé API limitée ou secrète est exposée ou compromise, renouvelez-la immédiatement, même si vous n’êtes pas certain qu’elle ait été consultée. Considérez toute exposition comme une compromission potentielle.

- L’*exposition* désigne toute situation où une clé devient visible dans un endroit inapproprié - par exemple dans un dépôt public, un fichier journal ou un e-mail - alors qu’elle aurait dû rester strictement confidentielle.
- La *compromission* correspond à toute situation où des éléments indiquent une utilisation non autorisée de la clé.

### Que faire en cas d’exposition ou de compromission d’une clé ?

Si vous découvrez qu’une clé API limitée ou secrète a été exposée ou compromise, suivez les instructions sur [cette page du service de support](https://support.stripe.com/questions/protecting-against-compromised-api-keys) pour limiter les dommages potentiels pour votre entreprise.

### Protection proactive des clés Stripe

Si Stripe détecte qu’une clé API secrète ou restreinte a été exposée, nous vous en informons et vous demandons de la renouveler. Dans certains cas, Stripe peut désactiver la clé de manière proactive et vous notifier des mesures prises.

Stripe ne garantit pas la détection de toutes les clés exposées ou compromises. L’application de ces bonnes pratiques vous aide à prévenir toute exposition de clé et à maintenir la sécurité de votre intégration avec Stripe.

## Clés API gérées

Certaines plateformes serveur ou hébergeurs peuvent [gérer les clés API Stripe](https://docs.stripe.com/keys/managed-api-keys.md) pour le compte de leurs clients, y compris les étapes de provisionnement et de rotation. Les clés API gérées restent sur la plateforme serveur, qui les fournit à votre code côté serveur. Le [Dashboard Stripe](https://dashboard.stripe.com/apikeys) affiche vos clés API gérées, mais ne révèle pas les clés complètes.

Comme les clés API gérées sont des données sensibles dans un environnement serveur, suivez les bonnes pratiques de ce guide pour les protéger. Ne codez jamais en dur les clés API gérées dans votre code côté serveur et n’exposez jamais directement les variables d’environnement depuis votre application.

Si votre plateforme serveur fournit des clés API Stripe gérées à votre application sous forme de variables d’environnement et permet de marquer certaines variables d’environnement comme *sensibles* pour activer des protections supplémentaires, veillez à marquer toutes les clés Stripe comme sensibles.

Si vous pensez qu’une clé API gérée a été exposée ou compromise, [renouvelez-la depuis le Dashboard Stripe](https://docs.stripe.com/keys.md#rolling-keys) ou depuis la plateforme serveur. Si vous renouvelez une clé API gérée dans le Dashboard, ou si Stripe détecte qu’elle a été compromise et la désactive pour protéger votre compte Stripe, nous synchronisons automatiquement ce changement avec votre plateforme serveur : vous n’avez pas besoin de modifier la clé à deux endroits.

Lorsque vos clés API gérées changent, vous devez généralement redéployer les applications correspondantes côté serveur, sauf si votre plateforme serveur effectue ce redéploiement automatiquement.

## See also

- [Clés API](https://docs.stripe.com/keys.md)
- [Protéger vos clés API contre la compromission](https://support.stripe.com/questions/protecting-against-compromised-api-keys)