Stocker des identifiants et des tokens dans votre application

Utilisez l'API Secret Store pour conserver des données sensibles, telles que les identifiants d'authentification.

L’API Secret Store permet de définir, rechercher, lister et supprimer de manière sécurisée des clés secrètes persistantes utilisées dans Stripe Apps. Ces identifiants, aussi appelés clés secrètes, sont uniquement accessibles par votre application et les utilisateurs propriétaires.

Aperçu

L’API Secret Store permet à votre application de :

Stocker et récupérer des identifiants d’authentification de manière sécurisée
Permettre à vos utilisateurs de rester authentifiés auprès d’un service tiers même s’ils se déconnectent de stripe.com puis s’y reconnectent
Transmettre des clés secrètes de votre extension d’interface utilisateur au back-end en toute sécurité

Mise en garde

Dans le cadre de la conformité PCI, Stripe ne vous autorise pas à stocker des données personnelles sensibles, des numéros de compte personnels tels que des numéros de carte bancaire et autres données en utilisant l’API Secret Store.

Champs d’application

Les clés secrètes d’une application chargée sont uniquement accessibles par les autres applications que vous avez chargées. Vous ne pouvez publier qu’une seule application par compte. Les applications publiées ne peuvent donc jamais partager de clés secrètes. Les requêtes effectuées par des applications tierces ne peuvent en aucun cas accéder aux clés secrètes de votre application.

Utilisez des champs d’application pour déterminer de manière plus approfondie l’accessibilité d’une clé secrète donnée. Un champ d’application est un ensemble de clés secrètes identifié par son accessibilité.

L’API Secret Store prend en charge les types de champs d’application suivants :

Type de champ d’application	Limites du champ d’application	Stocke jusqu’à	À utiliser pour :	Accessible :
champ d’application du compte	Il y a un champ `account` par application. Exemple : clé API tierce	Un maximum de 10 clés secrètes	Clés secrètes qui s’appliquent à tous les utilisateurs d’un compte Stripe qui installent votre application	À tous les utilisateurs du Dashboard d’un compte Stripe et au back-end de l’application, par application
champ d’application de l’utilisateur	Chaque utilisateur dispose d’un champ `user` sur chaque application. Exemple : token d’accès OAuth	Un maximum de 10 clés secrètes	Clés secrètes qui s’appliquent uniquement à un utilisateur spécifique d’un compte Stripe	À un utilisateur spécifique du Dashboard d’un compte Stripe et au back-end de l’application, par application

Le diagramme ci-dessous illustre le champ d’application des clés secrètes suivantes :

Le compte Stripe : « Le compte Stripe Cactus Practice »
Deux utilisateurs partageant le même compte Stripe : « User 1 », « User 2 »
Deux applications distinctes installées par le compte Stripe : « Installed App A », « Installed App B »
Clés secrètes correspondant au account : clé secrète « Foo API key » pour l’application A, « Bar API key » pour l’application B
Clés secrètes correspondant à user : « token OAuth access », « token OAuth refresh »

Les clés secrètes correspondant aux deux applications distinctes installées par le compte Stripe Cactus Practice.

Expiration

Si une clé secrète devient non valide dans le futur, vous pouvez indiquer une date d’expiration en définissant le paramètre facultatif expires_at au moment de la configuration de la clé. Ce paramètre accepte l’horodatage Unix (le nombre de secondes écoulées depuis la création du système Unix).

Une fois la date expires_at passée, la clé secrète est automatiquement supprimée de l’API Secret Store.

La date d’expiration ne peut pas être antérieure à la date actuelle ni être située plus de 100 ans dans le futur.

Configurer une clé secrète

Ajoutez l’autorisation secret_write à votre application :

Command Line
stripe apps grant permission "secret_write" "Allows storing secrets between page reloads"

Configurez une clé secrète par nom et par champ d’application dans l’API Secret Store. Vous pouvez utiliser l’exemple de code suivant dans le back-end ou l’extension d’interface utilisateur de votre application :

App.tsx
Extension d'interface utilisateur
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import Stripe from 'stripe';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// You don't need an API Key here, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.create({
      scope: { type: 'user', user: userContext.id },
      name: 'secret_name',
      payload: 'secret value',
      expires_at: 1956528000  // optional
    }).then(resp => console.log(resp));
  }, []);

  return null;
};

export default App;

Pour en savoir plus, consultez la documentation de l’API consacrée à la configuration d’une clé secrète.

Accéder à une clé secrète

Vous pouvez rechercher une clé secrète par nom et par champ d’application dans l’API Secret Store. Ainsi, vous pouvez utiliser l’exemple de code suivant dans le back-end ou l’extension d’interface utilisateur de votre application :

App.tsx
Extension d'interface utilisateur
import Stripe from 'stripe';
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// You don't need to use an API key, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.find({
      scope: { type: 'user', user: userContext.id },
      name: 'secret_name',
      expand: ['payload'],
    }).then(resp => console.log(resp.payload));
  }, []);

  return null;
};

export default App;

Pour en savoir plus, consultez la page Accéder à une clé secrète.

Supprimer une clé secrète

Pour supprimer une clé secrète par nom et par champ d’application dans l’API Secret Store, vous pouvez utiliser l’exemple de code suivant dans le back-end ou l’extension d’interface utilisateur de votre application :

App.tsx
Extension d'interface utilisateur
import Stripe from 'stripe';
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// Note that you don't need to use an API key, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.deleteWhere({
      scope: { type: 'user', user: userContext.id },
      name: 'secret_name',
    }).then(resp => console.log(resp));
  }, []);

  return null;
};

export default App;

Pour en savoir plus, consultez la page Supprimer une clé secrète.

Lister les clés secrètes

Si vous avez enregistré le nombre maximal de clés secrètes dans un champ d’application account ou user et que vous souhaitez en ajouter une autre, vous devez supprimer au moins une des dix clés. Vous pouvez générer une liste de toutes les clés secrètes d’un champ d’application donné afin de déterminer celles à supprimer.

Pour lister les clés secrètes d’un champ d’application account ou user, vous pouvez utiliser l’exemple de code suivant dans le back-end ou l’extension d’interface utilisateur de votre application :

App.tsx
Extension d'interface utilisateur
import Stripe from 'stripe';
import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useEffect } from 'react';

// Create an instance of a Stripe object to access customer information.
// Note that you don't need to use an API key, because the app uses the
// dashboard credentials to make requests.
const stripe: Stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient() as Stripe.HttpClient,
  apiVersion: '2024-11-20.acacia',
});

const App = ({userContext}: ExtensionContextValue) => {
  useEffect(() => {
    stripe.apps.secrets.list({
      scope: { type: 'user', user: userContext.id },
    }).then(resp => console.log(resp.data));
  }, []);

  return null;
};

export default App;

Pour en savoir plus, consultez la page Lister les clés secrètes.

Exemples d’applications

Les exemples d’application suivants expliquent comment utiliser l’API Secret Store :