# Clés API limitées

Utilisez des clés API limitées pour contrôler l’accès de votre application à l’API Stripe.

Vous pouvez utiliser une clé API restreinte (RAK) pour attribuer des autorisations spécifiques de l’API Stripe à vos clés API. L’utilisation d’une RAK de cette manière limite les dommages potentiels pour votre entreprise si une clé API est exposée à un acteur malveillant. Si une clé API restreinte ne dispose pas des autorisations nécessaires pour exécuter une requête API, Stripe renvoie une [erreur de requête invalide](https://docs.stripe.com/error-handling.md#invalid-request-errors).

## Qu’est-ce qu’une clé API limitée ?

Lorsque vous vous inscrivez à Stripe, vous recevez une [clé API secrète](https://docs.stripe.com/keys.md#obtain-api-keys) (qui commence par `sk_live_` ou `sk_test_`). Toute personne, tout agent ou tout système disposant de cette clé secrète peut *tout* faire dans votre compte Stripe : créer des paiements, émettre des remboursements, consulter les données des clients, déclencher des virements, et bien plus encore.

Une clé API limitée (RAK) commence par `rk_live_` ou `rk_test_` et ne peut effectuer que les actions que vous définissez. Lorsque vous créez une RAK dans le Dashboard Stripe, vous choisissez les ressources Stripe auxquelles la clé peut accéder ainsi que les autorisations pour chacune : **Lecture**, **Écriture** ou **Aucune**. Toutes les API Stripe prennent en charge les clés API limitées.

Vous pouvez utiliser des clés limitées comme mesure de protection pour sécuriser votre compte Stripe en cas d’exposition ou de compromission de vos clés. Si un acteur malveillant obtient une clé API limitée, il est limité aux autorisations associées à cette clé. Par exemple, vous pouvez créer une clé limitée qui permet uniquement de consulter les données de litiges, et rien d’autre. Si un acteur malveillant obtenait cette clé, il ne pourrait que lire ces données. Il ne pourrait ni créer des paiements, ni accéder aux moyens de paiement des clients, ni déclencher des virements.

Stripe recommande d’utiliser systématiquement des clés limitées plutôt que des clés secrètes non limitées. Respectez toujours les bonnes pratiques lors de l’utilisation de clés limitées afin d’éviter toute exposition ou compromission accidentelle. Consultez les [bonnes pratiques de gestion des clés API secrètes](https://docs.stripe.com/keys-best-practices.md).

## Pourquoi utiliser des clés limitées plutôt que des clés secrètes ?

|                                    | Clé secrète (`sk_`)                                     | Clé limitée (`rk_`)                                                    |
| ---------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Étendue de l’accès**             | Accès complet à toutes les ressources de l’API          | Seules les autorisations que vous attribuez                            |
| **Impact en cas de compromission** | Un acteur malveillant peut tout faire dans votre compte | Un acteur malveillant ne peut faire que ce que la clé permet           |
| **Partage avec des tiers**         | Dangereux : donne un contrôle total au tiers       | Plus sûr : vous ne fournissez que les accès nécessaires au tiers  |
| **Principe du moindre privilège**  | Impossible à appliquer avec des clés non limitées       | Vous pouvez attribuer des autorisations minimales aux clés             |
| **Recommandation de Stripe**       | Utiliser avec parcimonie et protéger de manière stricte | **Préféré** : utiliser des clés limitées chaque fois que possible |

### Raisons de passer aux clés API limitées

- **Limiter l’impact d’une compromission de clé** : si une clé limitée est compromise, un acteur malveillant ne peut accéder qu’aux ressources spécifiques que vous avez autorisées pour cette clé.

- **Partager des clés en toute sécurité avec des tiers** : Stripe déconseille le partage des clés dans la plupart des cas, mais pour certaines intégrations tierces, il peut être nécessaire de partager une clé. Par exemple, si un fournisseur doit surveiller vos litiges, fournissez-lui une clé limitée avec un accès en lecture seule aux litiges, plutôt que votre clé secrète non limitée. Si vous travaillez avec un tiers, assurez-vous qu’il respecte les [bonnes pratiques](https://docs.stripe.com/keys-best-practices.md) pour gérer la clé en toute sécurité, par exemple en utilisant une liste d’adresses IP autorisées si possible afin de réduire le risque de compromission de la clé, et en révoquant la clé lorsque la relation prend fin.

- **Répondre aux exigences de conformité** : de nombreux audits de sécurité et cadres de conformité exigent le respect du principe du moindre privilège. Les clés limitées permettent de s’y conformer facilement.

- **Combiner avec des restrictions IP** : vous pouvez restreindre toute clé limitée à un ensemble spécifique d’adresses IP pour ajouter une couche de protection supplémentaire.

## Migrer d’une clé secrète vers une clé limitée

Les clés API limitées sont des remplacements directs des clés API secrètes. Pour utiliser une clé API limitée, fournissez-la à votre code de la même manière que vous fournissez votre clé secrète, en suivant les [bonnes pratiques](https://docs.stripe.com/keys-best-practices.md) afin d’éviter toute exposition accidentelle de la clé. Toutes les API Stripe prennent en charge les clés API limitées. Vous devez configurer les autorisations de chaque clé limitée pour en tirer pleinement les bénéfices.

Voici une approche étape par étape pour migrer d’une clé secrète vers une clé API limitée. Consultez [Attribuer des autorisations à une clé API limitée](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) pour comprendre comment réduire les autorisations d’une clé limitée.

### Vérifier l’utilisation de l’API de la clé secrète

Passez en revue votre code ainsi que toutes les intégrations tierces afin d’identifier les produits Stripe que vous utilisez et les appels à l’API que vous effectuez actuellement avec votre clé secrète.

Passez en revue les [logs de requêtes de la clé secrète dans Workbench](https://dashboard.stripe.com/workbench/logs). Vous pouvez utiliser le tableau ci-dessous pour associer les requêtes API réussies aux autorisations de clé API limitée dont elles ont besoin.

| Méthode HTTP | Type d’autorisation RAK |
| ------------ | ----------------------- |
| GET          | lire                    |
| POST         | écrire                  |
| DELETE       | écrire                  |

Par exemple, si vous voyez des appels réussis à `GET /v1/customers`, vous devez ajouter des autorisations de lecture pour la ressource [Customer](https://docs.stripe.com/api/customers.md) aux autorisations RAK de remplacement.

### Créer une clé limitée dans un environnement de test

Stripe recommande de créer une clé limitée dans un environnement de test Stripe avant de créer une clé en mode production.

1. Accédez à la [page clés API](https://dashboard.stripe.com/apikeys) du Dashboard Stripe
1. Cliquez sur **Créer une clé limitée**.
1. Donnez-lui un nom descriptif, par exemple `billing-service-test`.
1. Pour chaque ressource, définissez l’autorisation sur **Aucun**, **Lecture** ou **Écriture** en fonction de l’utilisation de l’API observée précédemment.

### Configurez votre environnement de simulation pour utiliser la clé limitée

Dans votre application de test ou de simulation, remplacez la clé secrète par la clé API limitée dans votre environnement serveur (par exemple, dans une variable d’environnement ou un coffre de secrets). Le SDK Stripe et les appels HTTP utilisant votre clé fonctionnent de manière identique. La seule différence réside dans la valeur de la clé.

### Passez en revue les logs de requêtes de la clé API limitée pour détecter les erreurs et ajustez les autorisations.

Passez en revue les logs de la clé API limitée en mode test depuis la [liste des clés](https://dashboard.stripe.com/apikeys) en cliquant sur le menu de débordement (⋯) à côté de la clé, puis en sélectionnant **Afficher les logs de requêtes**.

Si vous trouvez des messages d’erreur tels que `403 ERR`, modifiez les autorisations de la clé limitée pour ajouter les actions qui ont échoué :

1. Cliquez sur le menu de débordement (⋯) à côté de la clé.
1. Sélectionnez **Modifier la clé**.
1. Répétez vos tests dans un environnement de test afin de confirmer que vous avez attribué les autorisations correctes à la clé API limitée.

Consultez les logs de votre application pour détecter les erreurs liées à l’API Stripe. Si la clé API limitée envoyée avec une requête ne dispose pas des autorisations appropriées, le corps de la réponse inclut un message d’erreur indiquant quelles autorisations ajouter.

### Créer une clé limitée en mode production

Créez une nouvelle clé limitée en mode production avec des autorisations qui correspondent à la clé du mode test que vous avez testée.

### Configurer votre environnement de production pour utiliser la clé limitée

Utilisez la nouvelle clé dans votre environnement de production de la même manière que vous avez configuré la clé de test dans votre environnement de simulation.

### Retirez l’ancienne clé secrète

Lorsque vous êtes sûr que tout fonctionne en mode test, [faites pivoter](https://docs.stripe.com/keys.md#rolling-keys) ou [faites expirer](https://docs.stripe.com/keys.md#delete-secret-key) votre ancienne clé secrète dans le Dashboard. Cela garantit que personne ne pourra l’utiliser à l’avenir. Vous pouvez définir une expiration différée (jusqu’à 7 jours) si vous souhaitez conserver une marge de sécurité pendant laquelle vous pouvez encore revenir à la clé secrète.

## Attribuer des autorisations à une clé API limitée

Vous pouvez configurer des clés API limitées en fonction de vos cas d’usage spécifiques, conformément au principe du moindre privilège : une clé doit disposer des autorisations minimales nécessaires pour accomplir sa tâche, et rien de plus. Voici plusieurs approches pratiques pour attribuer des autorisations.

### Auditez les logs de requêtes pour déterminer les autorisations.

1. Accédez à la page [API Keys](https://dashboard.stripe.com/apikeys) du Dashboard
1. Trouvez la clé limitée que vous configurez.
1. Cliquez sur le menu de débordement (⋯) à côté de la clé.
1. Cliquez sur **Afficher les logs de requêtes** pour afficher toutes les requêtes effectuées avec cette clé.

Passez en revue les endpoints de l’API utilisés par votre application lors de vos tests avec la clé API limitée afin d’identifier précisément les ressources utilisées et de déterminer si vous les avez consultées en lecture ou modifiées en écriture :

- Les requêtes `GET` correspondent à des opérations de lecture
- Les requêtes `POST` et `DELETE` correspondent à des opérations d’écriture

Si votre application a fonctionné correctement lors de vos tests, dressez une liste des appels réussis dans les logs de requêtes, puis comparez cette liste aux autorisations que vous avez accordées à la clé API limitée. Vous pouvez supprimer toute autorisation que votre clé n’a pas utilisée. Pour modifier les autorisations de la clé :

1. Cliquez sur le menu déroulant (⋯).
1. Cliquez sur **Modifier la clé**.

Si votre application ne fonctionne pas correctement, vous pouvez filtrer les logs de requêtes de la clé pour afficher les requêtes échouées, puis modifier les autorisations de la clé dans le menu des clés afin d’ajouter les autorisations API Stripe correspondantes.

### Vérifiez votre code

Vous pouvez établir une liste des autorisations requises en recherchant les appels au SDK Stripe dans votre base de code. Associez chaque appel à l’autorisation correspondante dans le Dashboard. Par exemple :

- `PaymentIntent.create(...)` → **PaymentIntents: Write**
- `Customer.retrieve(...)` → **Customers: Read**
- `Dispute.list(...)` → **Disputes: Read**

Ensuite, configurez les autorisations de votre clé limitée pour correspondre uniquement à ce que vous avez trouvé.

### Commencez avec des autorisations larges, puis supprimez celles dont vous n’avez pas besoin

Vous pouvez initialement accorder à une clé API limitée des autorisations étendues, puis supprimer les autorisations superflues après avoir examiné la manière dont la clé est utilisée.

Dans un environnement de test, créez une clé API limitée depuis le menu des clés API. Les autorisations disponibles sont regroupées par catégories. Si vous savez que votre utilisation de l’API Stripe n’inclut pas une catégorie particulière, comme Stripe Billing, vous pouvez sélectionner **Aucune** pour cette catégorie. Sinon, sélectionnez **Écriture** pour les catégories pertinentes à votre utilisation de l’API Stripe. Les autorisations **Écriture** incluent les autorisations **Lecture** : si une clé peut écrire sur une ressource API, elle peut également la lire.

Testez votre application avec la clé API limitée en mode test, comme décrit ci-dessus, afin que votre application utilise cette clé pour effectuer des requêtes à l’API Stripe. Testez chaque composant de votre application qui utilise les API Stripe.

## Utilisez une clé API limitée par service ou par cas d’usage

Si vous avez plusieurs services qui utilisent les API Stripe (par exemple, un service de facturation, un service de reporting et un gestionnaire de webhooks), créez une clé API limitée distincte pour chaque service, et attribuez à chaque clé uniquement les autorisations API Stripe dont ce service a besoin. Accorder des autorisations séparées permet de limiter l’impact potentiel d’une compromission de clé si l’un de vos services est compromis.