The Secret Store API is a way to securely set, find, list, and delete persistent secrets used in Stripe Apps. These credentials, also known as secrets, are only accessible to your app and the users who own them.
The Secret Store API enables your app to:
- Securely store and retrieve authentication credentials
- Keep users authenticated with third-party services, even if they sign out of
stripe.comand sign in again
- Securely pass secrets between your UI extension and backend
Stripe does not permit you to store sensitive personal data, personal account numbers such as credit card numbers, and other data within PCI Compliance using the Secret Store API.
The secrets of an uploaded app are only accessible by other apps that you’ve uploaded. You can only publish one app on an account, so published apps can never share secrets. Requests made by third-party apps can’t ever access your app’s secrets.
Use scopes to further specify the accessibility of a given secret. A scope is a collection of secrets identified by its accessibility.
The Secret Store API supports the following scope types:
|Scope type||Scope limits||Stores up to||Use for||Accessible to|
|account scope||There’s one ||A maximum of 10 Secrets||Secrets that apply to all users of a Stripe account that installs your app||All Dashboard users of a Stripe account and the app’s backend, on a per-app basis|
|user scope||Each user has one ||A maximum of 10 Secrets||Secrets that only apply to a specific a user of a Stripe account||A specific Dashboard user of a Stripe account and the app’s backend, on a per-app basis|
The diagram below shows the secret scoping between the following:
- The Stripe account: “The Cactus Practice Stripe account”
- Two users sharing the same Stripe account: “User 1”, “User 2”
- Two different apps installed by the Stripe account: “Installed App A”, “Installed App B”
accountscoped secrets: “Foo API key” secret for App A, “Bar API key” for App B
userscoped secrets: “OAuth access token”, “OAuth refresh token”
If a secret becomes invalid at some point in the future, you can specify an expiration time by setting the optional
expires_at parameter when you set a secret. This parameter takes in a Unix timestamp (the number of seconds elapsed since the Unix epoch).
expires_at date has passed, the secret is automatically deleted from the Secret Store API.
Expiration times can’t be in the past and can’t be more than 100 years in the future.
The following example apps demonstrate how to use the Secret Store API: