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 roll API keys. To access your v1 API keys, select the API Keys tab in your Dashboard.

Test mode versus live mode

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

Secret and publishable keys

All accounts have a total of four API keys by default – two for test mode and two for live mode:

• Test mode secret key: Use this key to authenticate requests on your server when in test mode. By default, you can use this key to perform any API request without restriction.
• Test mode publishable key: Use this key for testing purposes in your web or mobile app’s client-side code.
• Live mode secret key: Use this key to authenticate requests on your server when in live mode. By default, you can use this key to perform any API request without restriction.
• Live mode publishable key: Use this key, when you’re ready to launch your app, in your web or mobile app’s client-side code.

You can find your secret and publishable keys in API keys. When you’re logged in, Stripe’s documentation automatically populates code examples with your test mode API keys (only you can see these values). If you’re not logged in, our code examples include randomly generated API keys. You can replace them with your own test keys or log in to see the code examples populated with your test API keys. 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.

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

Keep your keys safe

Anyone can use your live mode secret API key to make any API call on behalf of your account, such as creating a charge or performing a refund. Keep your keys safe by following the secret API keys best practices.

Customise API access with restricted API keys

To provide limited access to the API, create restricted API keys. You can configure a restricted API key to allow read or write access to specific API resources. When using microservices that interact with the API on your behalf, define restricted keys that allow only the minimum access those microservices require. For example, if you use a dispute monitoring service, create a restricted key that only provides read access to dispute-related resources. That key allows the service to get the data it needs, but doesn’t allow it to make any changes or access any other data.

Restricted keys can’t interact with many parts of Stripe’s API because they’re only intended to reduce risk when using or building microservices. Don’t use restricted keys as an alternative to your account’s secret or publishable API keys during development of your Stripe integration.

Limit the IP addresses that can send API requests

You can increase the security of a secret or restricted key by limiting the IP addresses that can use it to send API requests. Additionally, you can restrict a key to one or more IP addresses or to a range of IP addresses.

Reveal a secret API key for test mode

In test mode, you can reveal a secret API key as many times as you want.

To reveal a secret key in test mode:

1. In the Developers Dashboard, select the API keys tab.
2. In the Standard keys list, in the Secret key row, click Reveal test key.
3. Copy the key value by clicking it.
4. Save the key value.
5. Click Hide test key.

Reveal a secret or restricted API key for live mode

For security, in live mode Stripe only shows you a secret or restricted API key one time. Store the key in a safe place where you won’t lose it. To help yourself remember where you stored it, you can leave a note on the key in the Dashboard. If you lose the key, you can roll it or delete it and create another.

To reveal a secret or restricted key in live mode and attach a note:

1. In the Developers Dashboard, select the API keys tab.
2. In the Standard keys list or Restricted keys list, in the row for the key you want to reveal, click Reveal live key.
3. Copy the key value by clicking it.
4. Save the key value.
5. Click Hide test key.
6. Click the overflow menu () next to the key, then select Edit key….
7. In the Note field, enter the location where you saved the key, then click Save.
8. If you created the key before Stripe introduced this feature, click Hide live key.

Roll an API key

Rolling a key revokes it and generates a replacement key. You can roll a key immediately or schedule a key to roll after a certain time. Roll a key in scenarios such as the following examples:

• If you’re in live mode and you lose a secret key or restricted key, you can’t recover it from the Dashboard and must replace it.
• If a secret or restricted key is compromised, you need to revoke it to block any potentially malicious API requests that might use it.
• Your policy requires rotating keys at certain intervals.

To roll an API key:

1. Open the API keys page.
2. In the row for the key you want to roll, click the overflow menu (), then select Roll key….
3. Choose an expiry date from the Expiry dropdown.
4. Click Roll API key.
5. The window displays the new key value. Copy it by clicking 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 and click Done or Save.

If you chose Now for the Expiry, we delete the old key. If you selected a different time, you can see the time remaining until the key expires below its name.

Regardless of the old key’s expiry time, the new key is ready to use immediately.

When you roll a publishable key, the replacement key’s name is always Publishable key. When you roll a secret key, the replacement key’s name is always Secret key. When you roll a restricted key, the replacement key’s name is the same as the rolled key. You can rename a secret or restricted key by clicking its overflow menu and selecting Edit key….

Delete a secret or restricted API key

If you delete a key, any code that uses that key can no longer make API calls. Create a new key and update the code to use it.

To delete a key:

1. In the Developers Dashboard, select the API keys tab.
2. Locate the key you want to delete in either the Standard keys or Restricted keys list. Click the overflow menu icon () in the row of that key, then select Delete key….
3. In the Delete API key window, if you’re sure that you want to delete the key, click Delete key. Otherwise, click Cancel.

Create a secret API key

To create a secret API key:

1. Open the API keys page.
2. Click Create secret key.
3. Stripe sends a verification code to your email address or in a text message. (As with any email or text message, it might not arrive immediately.) Enter the code in the window. If the window doesn’t continue automatically, click Continue.
4. Enter a name in the Key name field.
5. Click Create.
6. The window displays the new key value. Copy it by clicking 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 and click Done.

Create a restricted API key

A restricted API key only allows the level of access that you specify.

To create a restricted API key:

1. Open the API keys page.
2. You can create a restricted key from scratch or start by cloning an existing restricted key.
   • To create a restricted key from scratch, click Create restricted key. In this case, the default value for all permissions is None.
   • To clone an existing key, in the row for the key you want to clone, click the overflow menu (), then select Duplicate key…. In this case, the default value for each permission is its value in the cloned key.
3. In the Key name field, enter a name. If you cloned an existing key, the default name is the cloned key’s name.
4. For each resource you want the new key to access, select the permission for this key to allow. If you use Connect, you can also select the permission for this key to allow when accessing connected accounts. Available permissions are None, Read, or Write.
5. Click Create key.
6. Stripe sends a verification code to your email address or in a text message. (As with any email or text message, it might not arrive immediately.) Enter the code in the window. If the window doesn’t continue automatically, click Continue.
7. The window displays the new key value. Copy it by clicking it.
8. Save the key value. You can’t retrieve it later.
9. In the Add a note field, enter the location where you saved the key and click Done.

Limit secret or restricted keys to a list or range of IP addresses

To limit API requests using a key to one or more specific IP addresses or to a range of IP addresses:

1. Open the API keys page.
2. In the Standard keys list or Restricted keys list, in the row for the key you want to reveal, click the overflow menu (), then select Manage IP restrictions….
3. Click Limit use to a set of IP addresses.
4. Enter an IP address or range of IP addresses:
   • For an individual IP address, enter it in the IP address field.
   • For a range of IP addresses, enter the range in Classless Inter-Domain Routing (CIDR) notation. In the IP Address field, enter the first address in the range. In the CIDR field, enter the network prefix size.
   • You can also select the Bulk manage tab and enter individual IP addresses and ranges, separated by spaces. Changes you make in one tab appear in the other tab.
5. To add another address or range, click + Add.
6. Click Save.

Change a secret or restricted API key’s name or note

To change the name or note text of a secret or restricted key:

1. Open the API keys page.
2. In the row for the key you want to change, click the overflow menu (), then select Edit key….
3. If you want to change the name, in Key name, enter the new name.
4. If you want to change the note text, in Note, enter the new note text.
5. Click Save.

View the 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 main Stripe Dashboard.