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

By default, all accounts have a total of four API keys:

Your secret and publishable keys are on the API keys tab in the Dashboard. If you can’t view your API keys, 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 populates code examples with your test API keys. Only you can see these values. If you’re not logged in, our code examples include randomly generated API keys that you can replace with your test keys. Or you can log in to see the code examples populated with your test API keys.

Example API keys

The following table shows randomly generated examples of secret and publishable keys:

Protect your keys

Anyone can use your live mode secret key to make an API call on behalf of your account, such as creating a charge or performing a refund. Follow these best practices to keep your secret API keys safe.

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.

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.

Secret and restricted keys

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

Create an API key

You can create a secret API key or a restricted API key. A restricted API key only allows the level of access that you specify.

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.

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.

Reveal an API key

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

In live mode, Stripe only shows you the API key one time (for security purposes). Store the key in a place where you won’t lose it. 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 API key in a sandbox

1. On the API keys tab, in the Standard keys list, click Reveal test key in the Secret key row. You can reveal the secret API key as many times as you want.
2. Click the key value to copy it.
3. Save the key value.
4. Click Hide test key.

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.
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.

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 an individual IP address 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.

   You can also enter individual IP addresses and ranges (separated by spaces) on the Bulk manage tab. Changes you make in one tab appear in the other tab.

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.

Delete an API key

If you delete a secret API key or a restricted API key, you must create a new one and update any code that uses the deleted key. Any code that uses the deleted 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 delete.
2. Select Delete key.
3. In the dialog, click Delete key. If you no longer want to delete 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 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.

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.