Private preview

Managed API keys Private preview

Programmatically create and manage API keys on behalf of your app's users.

An approved Stripe App can programmatically create and manage API keys on behalf of your app’s users. App-managed keys eliminate the need for users to manually copy and paste secret keys from the app settings. They also allow you to manage key rotation and expiration while maintaining clear key ownership and audit trails.

Request to join the preview for managed API keys.

Enter your email to request access.

The following table summarizes the differences between user-managed and app-managed keys.

Common use cases for app-managed keys

Use app-managed API keys if your app:

• Works within a claimable sandbox workflow where you provision accounts on behalf of users.
• Serves non-technical users who might not be familiar with handling Stripe API keys.
• Handles key lifecycle changes, such as rotation and expiration, without user intervention.

Prerequisites

To use app-managed API keys, you must add the api_key_write permission to your Stripe App manifest. This permission requires explicit approval, so you must also submit your app to Stripe for review even if earlier versions were approved.

The standard app review process can take several days, but Stripe can expedite it for early access partners.

After we approve your app with this permission, it has access to the API Keys endpoints.

Installation requirements

Users must install your app using the standard Stripe App installation flow. App-managed keys can only be created after:

• The user has authorized your app.
• Your app has been granted the api _ key _ write permission.
• The user’s account is activated (for live mode keys).

Usage

Authenticate your API requests using an API key of your app. You can use either an unrestricted key or a restricted key that has the api_key_write Connect permission.

Create an API key on behalf of the user by calling an API Keys endpoint and including their Account ID in the Stripe-Context header.

For live mode secret keys, key tokens are encrypted and you must provide an RSA public key in PEM format. Tokens are encrypted using JSON Web Encryption (JWE) with RSA-the related setting and AES-256-GCM.

1. Generate an RSA key pair.

const crypto = require('crypto');

// Generate RSA key pair (minimum 2048 bits)
const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
 modulusLength: 2048,
 publicKeyEncoding: {
 type: "spki",
 format: "pem",
 },
 privateKeyEncoding: {
 type: "pkcs8",
 format: "pem",
 },
});

// Store privateKey securely (for example, in a secrets manager)
// Use publicKey in the API requests.

1. Create a secret key for a user’s account. Provide your public key to Stripe for encrypting the secret token.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

1. Decrypt the response payload using your private key.

const jose = require('jose');

const secretKeyCiphertext = secretKey.secret_key.encrypted_secret.ciphertext;

const importedPrivateKey = await jose.importPKCS8(privateKey, 'RSA-OAEP-256');
const { plaintext } = await jose.compactDecrypt(secretKeyCiphertext, importedPrivateKey);
const secretKeyToken = new TextDecoder().decode(plaintext);
// secretKeyToken is now ready to use (e.g., "sk_live_...")

1. Create a publishable key for a user’s account. Encryption isn’t supported for publishable keys, and tokens are returned in plaintext.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Access the token from the response:

const publishableKeyToken = publishableKey.publishable_key.token;

Listen to API key events

Use Connect webhooks to receive notifications about API key lifecycle changes for your users’ accounts. This allows your app to respond to key events such as rotation or expiration. Because these events occur on connected accounts rather than your platform account, you must use Connect webhooks—not Account webhooks—to receive them.

Configure your Connect webhook endpoint to listen for the following event types:

To set up a Connect webhook endpoint that receives events for your users’ accounts, see Connect webhooks.