アプリにシークレット認証情報やトークンを保存する

Secret Store API を使用すると、Stripe Apps で使用される永続シークレットの設定、検索、リスト、削除を安全に行うことができます。シークレットと呼ばれる認証情報には、アプリとシークレットを所有するユーザーのみがアクセスできます。

概要

Secret Store API を使用すると、アプリで以下を実行できます。

• 認証情報を安全に保存し、取得します
• ユーザーは、stripe.com からサインアウトして、再びサインインした場合でも、サードパーティーへの認証を維持できます
• UI 拡張機能とバックエンドの間でシークレットを安全に渡します

範囲

アップロードされたアプリのシークレットにアクセスできるのは、貴社がアップロードした他のアプリのみです。1 つのアカウントで公開できるアプリは 1 つのみのため、公開されたアプリはシークレットを共有できません。サードパーティーアプリによるリクエストが、貴社のアプリのシークレットにアクセスすることは不可能です。

範囲を使用して、特定のシークレットのアクセシビリティーをさらに詳細に指定できます。範囲とは、アクセシビリティーによって特定されるシークレットのコレクションです。

Secret Store API は、以下の範囲タイプをサポートしています。

以下の図は、次の間のシークレットの範囲を示しています。

• Stripe アカウント: 「The Cactus Practice Stripe account (Cactus Practice Stripe アカウント)」
• 同じ Stripe アカウントを共有している 2 人のユーザー: 「User 1」、「User 2」
• Stripe アカウントによってインストールされている 2 つのアプリ: 「Installed app A」、「Installed app B」
• account 範囲のシークレット: app A の「Foo API key」、app B の「Bar API key」
• user 範囲のシークレット: 「OAuth access token (OAuth アクセストークン)」、「OAuth refresh token (OAuth 更新トークン)」

Cactus Practice Stripe アカウントによってインストールされている 2 種類のアプリの範囲が設定されたシークレット。

有効期限

将来のある時点でシークレットを無効にする場合は、シークレットを設定する際にオプションの expires_at パラメーターを設定して、有効期限を指します。このパラメーターは Unix タイムスタンプ (Unix エポックから経過した秒数) を使用しています。

expires_at の日付を過ぎると、シークレットは Secret Store API から自動的に削除されます。

有効期限に過去の日付は設定できず、100 年後以降の日付にすることもできません。

Secret を設定する

1. アプリに secret_write 権限を追加します。

   Command Line

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

2. Secret Store API で名前と範囲を指定してシークレットを設定します。アプリの UI 拡張機能またはバックエンドでは以下のコードサンプルを使用できます。

   App.tsx

   UI 拡張機能

   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: '2025-04-30.basil',
   });
   
   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;

   詳細については、シークレットの設定に関する API リファレンスのドキュメントをご覧ください。

Secret を見つける

Secret Store API で名前と範囲を使用してシークレットを見つけることができます。たとえば、アプリの UI 拡張機能またはバックエンドで以下のコード例を使用します。

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: '2025-04-30.basil',
});

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;

詳細については、シークレットを探すをご覧ください。

Secret を削除する

Secret Store API で名前と範囲を使用してシークレットを削除するには、アプリの UI 拡張機能またはバックエンドで以下のコードサンプルを使用できます。

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: '2025-04-30.basil',
});

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;

詳細については、シークレットを削除するをご覧ください。

Secret を一覧表示する

account または user の範囲に最大数のシークレットを保存していて、別のシークレットを追加する場合は、10 個のシークレットのうち少なくとも 1 つを削除する必要があります。削除するシークレットを決定するために、特定の範囲のすべてのシークレットを一覧表示できます。

account または user の範囲のシークレットをリストするには、アプリの UI 拡張機能またはバックエンドで以下のコードサンプルを使用できます。

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: '2025-04-30.basil',
});

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;

詳細については、シークレットをリストアップするをご覧ください。

サンプルアプリ

以下のサンプルアプリは、Secret Store API の使用法を説明しています。

• シンプルなデモアプリ
• Dropbox OAuth with PKCE app (Dropbox OAuth with PKCE アプリ) (英語)