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.

You can use the Developers Dashboard to create, reveal, delete, and roll API keys. To access your v1 API keys, select the API Keys tab on 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:

1. 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.
2. Test mode publishable key: Use this key for testing purposes in your web or mobile app’s client-side code.
3. 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.
4. 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 on the API keys page in the Developers Dashboard. While you’re logged in, Stripe 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. Replace them with your own test keys or log in to see the code examples populated with your own 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 these best practices:

• Grant access only to those who need it.
• Don’t store keys in a version control system.
• Control access to keys with a password manager or secrets management service.
• Don’t embed a key where it could be exposed to an attacker, such as in a mobile application.

Customize 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. 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. On 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 once. 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. On 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, and select Edit key….
7. In the Note field, enter the location where you saved the key and 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. In Expiration, choose when to roll the existing key.
4. Click Roll API key.
5. The dialog 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 selected Now for the Expiration, the old key is gone. If you selected a different time, the time remaining until the key expires is displayed below its name.

Regardless of the old key’s expiration 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. On the Developers Dashboard, select the API keys tab.
2. In the Standard keys or Restricted keys list, in the row for the key you want to delete, click the overflow menu (), and select Delete key….
3. In the Delete API key dialog, 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 code to your email address. (As with any email, it might not arrive immediately.) Get the code and enter it in the dialog. If the dialog doesn’t continue automatically, click Continue.
4. Enter a name in the Key name field.
5. Click Create.
6. The dialog 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 code to your email address. (As with any email, it might not arrive immediately.) Get the code and enter it in the dialog. If the dialog doesn’t continue automatically, click Continue.
7. The dialog 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 Restrict IP addresses that can use the API key.
4. Enter a list or range of IP addresses:
   • For a list of IP addresses, enter the first IP address in the fields. For each additional IP address, click + Add IP address and enter the address.
   • For a range of IP addresses, click CIDR, then enter the range in Classless Inter-Domain Routing (CIDR) notation. In the first three fields, enter the first three numbers of the IP addresses in the range. In the fourth and fifth fields, enter the fourth number of the first and last addresses in the range, respectively.
5. 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

You can open the API request logs by clicking the overflow menu () for any key and selecting View request logs. Opening the logs returns you to the main Stripe Dashboard.