# 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 limitée (RAK) pour attribuer des autorisations API Stripe précises à vos clés API. L’utilisation d’une RAK de cette manière limite les dommages potentiels pour votre entreprise si une clé API venait à être divulguée à un acteur malveillant. Si une clé API limitée ne dispose pas des autorisations nécessaires pour traiter une requête API, Stripe renvoie une [erreur de requête non valide](https://docs.stripe.com/error-handling.md#invalid-request-errors).

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

Lorsque vous vous inscrivez sur Stripe, vous recevez une [clé API secrète](https://docs.stripe.com/keys.md#obtain-api-keys) (commençant par `sk_live_` ou `sk_test_`). Toute personne, tout agent ou tout système disposant de votre clé secrète peut effectuer *toutes les opérations* sur votre compte Stripe : créer des prélèvements, effectuer des remboursements, consulter les données des clients, déclencher des virements, etc.

Une clé API limitée (RAK) commence par `rk_live_` ou `rk_test_` et ne peut effectuer que les opérations que vous autorisez. Lorsque vous créez une RAK dans le Dashboard Stripe, vous sélectionnez les ressources Stripe auxquelles la clé peut accéder, ainsi que les autorisations pour chaque ressource : **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 sécurité pour protéger votre compte Stripe au cas où vos clés seraient divulguées ou compromises. Si un pirate informatique parvient à se procurer une clé API limitée, ses actions seront restreintes aux autorisations associées à cette clé. Par exemple, vous pouvez créer une clé limitée qui permet uniquement de consulter les données relatives aux litiges, et rien d’autre. Si un pirate informatique venait à obtenir cette clé, il ne pourrait que consulter ces données. Il ne pourrait pas créer de transactions, accéder aux modes de paiement des clients ni déclencher de virements.

Stripe recommande de toujours utiliser des clés limitées plutôt que des clés secrètes illimitées. Respectez toujours les bonnes pratiques lors de l’utilisation de clés limitées afin d’éviter toute divulgation ou compromission accidentelle. Consultez [Bonnes pratiques en matière 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 à chaque ressource API                                  | Uniquement les autorisations que vous attribuez                                      |
| **Impact en cas de compromission**    | Un pirate informatique peut faire tout ce qu’il veut sur votre compte | Un pirate informatique ne peut faire que ce que la clé lui permet                    |
| **Partage par des tiers**             | Dangereux : donne le contrôle total au tiers                     | Plus sécurisé : vous ne donnez accès qu’aux informations dont le tiers a besoin |
| **Principe du droit d’accès minimal** | Impossible à réaliser avec des clés illimitées                        | Vous pouvez attribuer des autorisations minimales aux clés                           |
| **Recommandation de Stripe**          | Utilisez avec parcimonie et protégez sans relâche                     | **Recommandé** : utilisez des clés limitées dans la mesure du possible          |

### Raisons du passage aux clés API limitées

- **Limiter l’impact d’une éventuelle prise de contrôle de clé** : si une clé limitée est compromise, un pirate ne pourra accéder qu’aux ressources précises auxquelles vous avez autorisé cette clé à accéder.

- **Partager des clés en toute sécurité avec des tiers** : Stripe déconseille le partage de clés dans la plupart des cas, mais pour certaines intégrations avec des tiers, vous pourriez être amené à 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, et non votre clé secrète illimité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 blanche d’adresses IP si possible afin de réduire le risque de compromission de la clé, et en faisant expirer la clé si la relation prend fin.

- **Respecter les exigences de conformité** : de nombreux audits de sécurité et cadres de conformité exigent que vous respectiez le principe du privilège minimal. Les clés limitées facilitent grandement cette tâche.

- **Associer à des restrictions d’adresse IP** : vous pouvez bloquer toute clé limitée à un ensemble précis d’adresses IP afin de bénéficier d’un niveau de protection supplémentaire.

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

Les clés API limitées remplacent directement les clés API secrètes. Pour utiliser une clé API limitée, intégrez-la à votre code de la même manière que vous le feriez pour une clé secrète, en suivant les [bonnes pratiques](https://docs.stripe.com/keys-best-practices.md) afin d’éviter toute divulgation 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 parti.

Voici une procédure étape par étape pour passer d’une clé secrète à une clé limitée. Consultez la section [Attribuer des autorisations à une clé API limitée](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) pour apprendre à restreindre les autorisations d’une clé limitée.

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

Vérifiez votre code et toutes les intégrations tierces afin de répertorier les produits Stripe que vous utilisez et les appels à l’API que vous effectuez actuellement avec votre clé secrète.

Vérifiez les [journaux de requêtes de la clé secrète dans Workbench](https://dashboard.stripe.com/workbench/logs). Vous pouvez utiliser le tableau ci-dessous pour mettre en correspondance les requêtes API réussies avec les autorisations RAK requises.

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

Par exemple, si vous constatez que les appels vers `GET /v1/customers` aboutissent, vous devez ajouter des autorisations de lecture pour la ressource [Client](https://docs.stripe.com/api/customers.md) aux autorisations d’un RAK de remplacement.

### Créer une clé limitée dans un bac à sable

Stripe recommande de créer une clé limitée dans un bac à sable Stripe avant de créer une clé en mode de production.

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

### Configurez votre environnement de test pour qu’il utilise la clé limitée

Dans votre application de test ou de préproduction, remplacez la clé secrète par la clé limitée dans votre environnement de serveur (par exemple, dans une variable d’environnement ou un coffre-fort de secrets). Le SDK Stripe et les appels HTTP qui utilisent votre clé fonctionnent de la même manière. La seule différence réside dans la valeur de la clé.

### Vérifiez les journaux de requêtes de la clé limitée pour détecter d’éventuelles erreurs et modifiez les autorisations

Vérifiez les journaux de la clé limitée en mode test à partir de la [liste des clés](https://dashboard.stripe.com/apikeys) en cliquant sur le menu déroulant (⋯) situé à côté de la clé, puis en sélectionnant **Afficher les journaux de requêtes**.

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

1. Cliquez sur le menu déroulant (⋯) à côté de la touche.
1. Sélectionnez **Modifier la clé**.
1. Répétez vos tests dans un bac à sable pour vérifier que vous avez bien attribué les autorisations appropriées à la clé limitée.

Vérifiez les journaux de votre application pour voir s’il y a des erreurs liées à l’API Stripe. Si la clé limitée envoyée avec une requête ne dispose pas des autorisations requises, le corps de la réponse contient un message d’erreur indiquant les autorisations à ajouter.

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

Créez une nouvelle clé à accès limité en mode production avec des autorisations identiques à celles de la clé en mode test que vous avez testée.

### Configurez votre environnement de production pour qu’il utilise 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 test.

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

Une fois que vous êtes certain que tout fonctionne correctement en mode test, [modifiez](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 plus l’utiliser à l’avenir. Vous pouvez définir une expiration différée (jusqu’à 7 jours) si vous souhaitez disposer d’une période de sécurité pendant laquelle vous pourrez encore revenir à l’ancienne clé secrète.

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

Vous pouvez configurer des clés limitées en fonction de vos cas d’usage précis, conformément au principe du droit d’accès minimal : une clé doit disposer des autorisations minimales nécessaires à l’accomplissement de sa tâche, et rien de plus. Voici plusieurs approches pratiques pour attribuer des autorisations.

### Analyser les journaux des requêtes d’autorisation pour déterminer les droits d’accès

1. Accédez à la page [Clés API](https://dashboard.stripe.com/apikeys) dans le Dashboard.
1. Trouvez la clé limitée que vous configurez.
1. Cliquez sur le menu déroulant (⋯) à côté de la touche.
1. Cliquez sur **Afficher les journaux des requêtes** pour voir toutes les requêtes effectuées avec cette clé.

Vérifiez les points de terminaison de l’API que votre application a utilisés lors de vos tests avec la clé à accès restreint afin de déterminer précisément quelles ressources votre application a utilisées et si vous y avez effectué des opérations de lecture ou d’écriture :

- Les requêtes `GET` sont des lectures
- Les requêtes `POST` et `DELETE` sont des écritures

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

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

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

### Vérifier votre code

Vous pouvez dresser la liste des autorisations requises en recherchant les appels à la trousse SDK Stripe dans votre code. Associez chaque appel à l’autorisation correspondante dans le Dashboard. Par exemple :

- `PaymentIntent.create(...)` → **PaymentIntents : Écrire**
- `Customer.retrieve(...)` → **Clients : Lire**
- `Dispute.list(...)` → **Litiges : Lire**

Configurez ensuite les autorisations de votre clé limitée afin qu’elles correspondent uniquement à ce que vous avez trouvé.

### Commencez par définir des autorisations générales, puis supprimez celles dont vous n’avez pas besoin

Vous pouvez dans un premier temps attribuer des autorisations étendues à une clé à accès restreint, puis supprimer les autorisations superflues après avoir examiné la manière dont la clé est utilisée.

Dans un bac à sable, créez une clé limitée à partir du 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 pour 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 lire cette ressource.

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

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

Si vous disposez de plusieurs services utilisant les API Stripe (par exemple, un service de facturation, un service de rapport et un gestionnaire de point d’ancrage Web), créez une clé limitée distincte pour chaque service et attribuez à chacune d’elles uniquement les autorisations API Stripe dont elle a besoin. L’octroi d’autorisations distinctes vous permet de limiter l’impact potentiel d’un détournement de clé si l’un de vos services venait à être compromis.