# 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.

## 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).

## Store API key securely 

Don’t put any keys in code. Use secrets management tools (such as a secrets vault) to supply keys to your integration. You can store keys in environment variables to test code samples.

### Set an API key as an environment variable

When you run code examples, set a temporary variable for your current terminal session. The environment variable clears when you close the terminal.

#### Mac/Linux

```bash
export STRIPE_API_KEY=sk_test_BQokikJOvBiI2HlWgH4olfQ2
```

### Reference the API key in your code

#### Ruby

```ruby
Stripe.api_key = ENV["STRIPE_API_KEY"]
```

## 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, vous pouvez créer des [clés API restreintes](https://docs.stripe.com/keys.md#create-restricted-api-secret-key) afin d’attribuer des autorisations spécifiques aux personnes et aux systèmes. 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 secrètes d’API compromises

Si une clé API 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é ?

Suivez les étapes ci-dessous dès que vous découvrez qu’une clé API secrète a été exposée ou compromise :

1. **Renouvelez immédiatement la clé concernée.** [Renouvelez la clé](https://docs.stripe.com/keys.md#rolling-keys) dans le [Dashboard Stripe](https://dashboard.stripe.com/apikeys), puis mettez à jour votre intégration avec la nouvelle clé. Si vous définissez une expiration différée de l’ancienne clé afin d’éviter tout temps d’indisponibilité, veillez à ce que cette période soit la plus courte possible.
1. **Identifiez les clés à renouveler.** A minima, renouvelez la clé spécifique qui a été exposée. Si l’étendue de l’exposition n’est pas clairement établie - par exemple en cas de compromission d’un serveur ou d’un coffre de stockage des identifiants - renouvelez l’ensemble des clés API secrètes et restreintes de votre compte.
1. **Examinez vos logs des requêtes API.** Consultez les [logs des requêtes API](https://docs.stripe.com/development/dashboard/request-logs.md) associés à la clé concernée. Recherchez toute requête inhabituelle, des adresses IP inconnues ou des schémas anormaux, tels qu’un pic soudain de volume ou des appels à des API Stripe que votre intégration n’utilise pas habituellement.
1. **Contactez le service de support de Stripe en cas d’activité non reconnue.** Si vos logs de requêtes révèlent des actions que vous ne pouvez pas expliquer, contactez le [service de support de Stripe](https://support.stripe.com/) afin d’obtenir de l’aide pour analyser la situation et en limiter l’impact.

### Protection proactive des clés par 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.

## 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)