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

認証情報などの機密データは、Secret Store API を使用して保存します。

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

概要

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

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

注意

Stripe では、Secret Store API を使用して機密個人データ、クレジットカード番号などの個人の口座番号、PCI 準拠のその他のデータを格納することを許可していません。

範囲

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

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

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

範囲タイプ	対象範囲の制限	保管できる最大数	用途	アクセスできるユーザー
アカウント範囲	アプリごとに 1 つの `account` スコープがあります。例: サードパーティーの API キー	最大 10 個のシークレット	アプリをインストールする Stripe アカウントのすべてのユーザーに適用されるシークレット	アプリ単位での Stripe アカウントのすべてのダッシュボードユーザーとアプリのバックエンド
ユーザー範囲	各ユーザーは、アプリごとに 1 つの `user` スコープを持ちます。例: OAuth アクセストークン	最大 10 個のシークレット	Stripe アカウントの特定のユーザーにのみ適用されるシークレット	アプリ単位での Stripe アカウントの特定のダッシュボードユーザーとアプリのバックエンド

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

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_write 権限を追加します。

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

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: '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;

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

シークレットを見つける

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

App.tsx
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: '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;

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

シークレットを削除する

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

App.tsx
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: '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;

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

シークレットをリストする

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

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

App.tsx
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: '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;

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

サンプルアプリ

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