API keys

Stripe authenticates your API requests using your account’s API keys. If a request doesn’t include a valid key, Stripe returns an invalid request error. If a request includes a deleted or expired key, Stripe returns an authentication error.

Use the Developers Dashboard to create, reveal, delete, and rotate API keys. You can access your v1 API keys on the API keys tab.

Key types

Stripe supports different types of API keys for different use cases. You’re responsible for managing these keys safely. In particular, treat secret keys and restricted API keys (RAKs) as sensitive and don’t expose them outside your server environment. To keep your business safe, read and understand best practices for managing secret API keys.

Develop and test and your application with sandbox keys, not live-mode keys, to make sure you don’t accidentally modify your live customers or charges.

Find your API keys in the Stripe dashboard. If you can’t view your API keys but need to manage keys for your app, ask the owner of your Stripe account to add you to their team with the proper permissions.

If you’re logged in to Stripe, our documentation includes your test API keys in some places to illustrate API usage. Only you can see these values. If you’re not logged in, our code examples include randomly generated API keys.

Protect your keys

Anyone can use your live mode secret key to make any API call on behalf of your account, such as creating a charge or performing a refund. You’re responsible for keeping your keys safe. Protect your keys by following these best practices:

• Store secret keys in a secrets vault or encrypted environment variables. Don’t store keys in source code or configuration files checked into version control.
• Use restricted API keys instead of secret keys when possible. Restricted keys limit access to only the specific API resources your integration needs, reducing the impact of a compromised key.
• Limit keys to specific IP addresses so they can only be used from your known servers.
• Rotate keys when team members with access to the keys leave your organization.
• Don’t share keys over email, chat, or other unencrypted channels.

For more detail, see best practices for managing secret API keys.

Sandbox versus live mode

All Stripe API requests occur in either a sandbox or live mode. You can use a sandbox to access test data, and live mode to access actual account data. Each mode has its own set of API keys, and objects in one mode aren’t accessible to the other. For example, a sandbox product object can’t be part of a live mode payment.

Switch to live mode

When you’re ready to accept real payments, use live mode API keys instead of sandbox (test) keys. On the API keys page, toggle from sandbox mode to live mode. The page now shows your live mode API keys.

Publishable keys (client-side)

1. Copy your live mode publishable key (starts with pk_live_) and replace the pk_test_ key in your client-side code.

Restricted or secret API keys (server-side)

Server-side API keys are sensitive, so review our best practices for managing secret API keys if you haven’t already. We recommend generating restricted API keys for your server-side code to limit the damage to your business if your keys are ever exposed or compromised.

1. Before you start using a live mode key in your backend application, remove any hardcoded secret (or restricted) API keys from your code. Instead, use a secrets vault or environment variable to supply the sandbox key, and confirm that your application still works.
2. Reveal and copy your live mode keys (start with rk_live_ or sk_live_) and store them securely in your server environment. Be careful—you can view each live-mode restricted or secret key only once.
3. Configure your server environment to supply live mode keys instead of sandbox keys to your application.
4. If you use webhooks, update each webhook endpoint’s URL and copy the new signing secret from the Webhooks section of the Dashboard.

Organization API keys

If you have multiple Stripe business accounts in an organization, you can configure a single API key at the organization level. Organization-level API keys provide the following functionality:

• Access any account: Use organization API keys to access resources of any account within the organization.

• Granular permissions: Restrict organization API keys to grant read or write permission to only specific resources.
• Centralized management: Create and manage organization API keys on the API keys tab of your organization’s Dashboard.

Behavior

Organization API keys behave differently from account-level API keys, including:

• They don’t have a publishable key. Treat all organization API keys as secret keys.
• They all have the same sk_org prefix, regardless of their permission levels.
• All API requests made with an organization API key must include the Stripe-Context header to identify the affected account.
• All API requests made with an organization API key must include the Stripe-Version header to ensure consistency and predictability across your organization’s integrations.

Use organization API keys

When you use an organization API key, you must also:

• Specify an API version by including a Stripe-Version header. When using a Stripe SDK, the SDK automatically sets the API version.
• Identify the account affected by the API request by including the Stripe-Context header.

For example, given the following organization structure:

Organization (org_6SD3oI0eSQemPzdmaGLJ5j6)
  ├── Platform account  (acct_1R3fqDP6919yCiFv)
  |   └── Connected account (acct_1032D82eZvKYlo2C)
  └── Standalone account (acct_1aTnTtAAB0hHJ26p)

You can use the organization API key to access the balance of the standalone account. You can also use the same key to make the same call for the platform connected account.

curl https://api.stripe.com/v1/balance \
  -u {{ORG_SECRET_KEY}}: \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

In the preceding code example, replace {{CONTEXT}} with the relevant value:

• For the standalone account, use acct_1aTnTtAAB0hHJ26p.
• For the connected account, use a path that identifies both the platform and the connected account, following the format acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C.

You must specify the relevant account using the context and the API version in any API request using an organization key.

Organizations don’t have publishable API keys because they can’t accept payments. You can use your organization API key to create a PaymentIntent for any account in your organization, but you must use existing account-specific publishable keys for the client-side operations.

Managed API keys

Some third-party platforms, such as Vercel, can create and manage API keys on your behalf when you install their integration. These keys are called managed API keys, and the platform creates them programmatically instead of you creating them manually in the Dashboard.

Managed API keys appear alongside your other keys on the API keys tab, labeled with the name of the managing platform.

The following table summarizes the differences between unmanaged and managed keys.

Revoke managed key access

You can revoke a managed API key at any time by doing one of the following:

• Expire the key: On the API keys tab, click the overflow menu () for the managed key and expire it. That immediately revokes the platform’s access without removing the integration.
• Uninstall the integration: Uninstall the platform’s app from your Stripe account. When you uninstall an app, you can choose to expire the managed keys immediately or keep them active.

Secret and restricted keys

Use the Dashboard to create, reveal, modify, delete, and rotate secret and restricted keys.

Create an API key

We recommend creating restricted API keys (RAKs) for most use cases. Using a RAK, you can assign exactly the permissions your integration needs, reducing the damage a bad actor could cause to your business if they obtained your key. Create an unrestricted secret API key only when your integration requires access to all Stripe APIs and resources.

To create a restricted API key

1. On the API keys tab, do one of the following:
   • To create a new restricted key, click Create restricted key. The default value for all permissions is None.
   • To clone an existing key, click the overflow menu (), then select Duplicate key for the key you want to clone. The default value for each permission is the value from the cloned key.
2. Enter a name in the Key name field. If you cloned an existing key, the default name is the cloned key’s name.
3. For each resource you want the new key to access, select the appropriate permission: None, Read, or Write. If you use Connect, you can also select the permission to allow for this key when accessing connected accounts.
4. Click Create key.
5. In the dialog, enter the verification code that Stripe sends to you by email or text message. If the dialog doesn’t continue automatically, click Continue.
6. Click the key value to copy it.
7. Save the key value. You can’t retrieve it later.
8. In the Add a note field, enter the location where you saved the key, then click Done.

To create a secret API key

1. On the API keys tab, click Create secret key.
2. In the dialog, enter the verification code that Stripe sends to you by email or text message. If the dialog doesn’t continue automatically, click Continue.
3. Enter a name in the Key name field, then click Create.
4. Click the key value to copy it.
5. Save the key value. You can’t retrieve it later.
6. In the Add a note field, enter the location where you saved the key, then click Done.

Reveal an API key

You can reveal a restricted or secret API key in a sandbox or live mode.

In live mode, Stripe shows you each restricted or secret API key only once. Store the key in a place where you won’t lose it, but not in your application’s code. To remind yourself where you stored it, you can add a note on the key in the Dashboard. If you lose the key, you can rotate or delete it and create another.

To reveal a secret or restricted API key in live mode

1. On the API keys tab in live mode, in the Standard keys or Restricted keys list, click Reveal live key for the key you want to reveal.
2. Click the key value to copy it.
3. Save the key value in a safe place, such as your platform’s secrets vault or backend environment variable configuration.
4. Click Hide test key.
5. Click the overflow menu (), then select Edit key for the key you want to add a note to.
6. In the Note field, enter the location where you saved the key, then click Save.

Limit an API key to certain IP addresses

You can limit a secret API key or a restricted API key to a range of IP addresses, or one or more specific IP addresses. Stripe recommends enabling IP restrictions on all live mode keys to prevent use from unauthorized locations. Use separate IP allowlists for separate keys when applicable (for example, to distinguish between staging and production environments).

IP addresses must use the IPv4 protocol, and you can specify any valid CIDR range. For example, you can specify the 100.10.38.0 - 100.10.38.255 range as 100.10.38.0/24. All IP addresses in the range must start with 100.10.38.

1. On the API keys tab, in the Standard keys or Restricted keys list, click the overflow menu () for the key you want to reveal.

2. Select Manage IP restrictions > Limit use to a set of IP addresses.

3. Do one of the following:

   • Enter one or more individual IP addresses in the IP address field.
   • For a range of IP addresses, enter the first address in the range (using Classless Inter-Domain Routing (CIDR) notation) in the IP Address field. Enter the network prefix size in the CIDR field.

4. To add another IP address or range, click + Add.

5. Click Save.

Change an API key’s name or note

1. On the API keys tab, click the overflow menu () for the key you want to change.
2. Select Edit key.
3. Do the following:
   • To change the name, enter a new name in the Key name field.
   • To change the note text, enter the new note text in the Note field.
4. Click Save.

Expire an API key

If you expire a secret API key or a restricted API key, you must create a new one and update any code that uses the expired key. Any code that uses the expired key can no longer make API calls.

1. On the API keys tab, in the Standard keys or Restricted keys list, click the overflow menu () for the key you want to expire.
2. Select Expire key.
3. In the dialog, click Expire key. If you no longer want to expire the key, click Cancel.

Rotate an API key

Rotating an API key revokes it and generates a replacement key that’s ready to use immediately. You can also schedule an API key to rotate after a certain time. The replacement key is named as follows:

• The replacement publishable key name is always Publishable key.
• The replacement secret key name is always Secret key.
• The replacement restricted key name is the same as the rotated key.

You can rename a secret or restricted API key by editing the key.

Rotate an API key in scenarios such as:

• If you lose a secret or restricted API key in live mode, and you can’t recover it from the Dashboard.
• If a secret or restricted API key is compromised, and you need to revoke it to block any potentially malicious API requests that might use the key.
• If a team member with access to the key leaves your organization or changes roles.
• If your policy requires rotating keys at certain intervals.

To rotate an API key

1. On the API keys tab, click the overflow menu () for the key you want to rotate.
2. Select Rotate key.
3. Select an expiration date from the Expiration dropdown. If you choose Now, the old key is deleted. If you specify a time, the remaining time until the key expires displays below the key name.
4. Click Rotate API key.
5. Click the key value to copy it.
6. Save the key value. You can’t retrieve it later.
7. In the Add a note field, enter the location where you saved the key, then click Save or Done.

Restore an API key’s access

An API key might have its access limited if it hasn’t been used to create transfers, payouts, or update payout destinations for over 180 days. You can’t use a limited access key to create payouts and transfers or to create payout destinations. You can restore access to use the key normally or to perform a blocked action.

To restore access for an API key

1. On the API keys tab, click the overflow menu () for the key you want to restore.
2. Select Restore access.
3. Click Restore.

View API request logs

To open the API request logs, click the overflow menu () for any key, then select View request logs. Opening the logs redirects you to the Stripe Dashboard.