API keys
Use API keys to authenticate API requests.
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.
Live mode key access
You can only reveal a live mode secret or restricted API key one time. If you lose it, you canât retrieve it from the Dashboard. In that case, roll it or delete it and create a new one.
Type | When to use | Objects | How to use | Considerations |
---|---|---|---|---|
test mode | Use test mode, and its associated test API keys, as you build your integration. In test mode, card networks and payment providers donât process payments. | API calls return simulated objects. For example, you can retrieve and use test account , payment , customer , charge , refund , transfer , balance , and subscription objects. | Use test credit cards and accounts. You canât accept real payment methods or work with real accounts. | Identity doesnât perform any verification checks. Also, Connect account objects donât return sensitive fields. |
live mode | Use live mode, and its associated live API keys, when youâre ready to launch your integration and accept real money. In live mode, card networks and payment providers do process payments. | API calls return real objects. For example, you can retrieve and use real account , payment , customer , charge , refund , transfer , balance , and subscription objects. | Accept real credit cards and work with customer accounts. You can accept actual payment authorizations, charges, and captures for credit cards and accounts. | Disputes have a more nuanced flow and a simpler testing process. Also, some payment methods have a more nuanced flow and require more steps. |
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.
Testing and development
Use only your test API keys for testing and development. This ensures that you donât accidentally modify your live customers or charges.
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:
Restricted API keys
The Dashboard can also generate restricted API keys, enabling customizable and limited access to the API. However, Stripe doesnât offer any restricted keys by default.
Type | Value | When to use |
---|---|---|
Secret | sk_ | On the server side: Must be secret and stored securely in your web or mobile appâs server-side code (such as in an environment variable or credential management system) to call Stripe APIs. Donât expose this key on a website or embed it in a mobile application. |
Publishable | pk_ | On the client side: Can be publicly accessible in your web or mobile appâs client-side code (such as checkout.js) to securely collect payment information, such as with Stripe Elements. By default, Stripe Checkout securely collects payment information. |
Restricted | A string that starts with rk_ | In microservices: Must be secret and stored securely in your microservice code to call Stripe APIs. Donât expose this key on a website or embed it in a mobile application. |
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.
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.
Permission errors
If you use a restricted API key in a call it doesnât have access to, Stripe raises a permission error.
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:
- In the Developers Dashboard, select the API keys tab.
- In the Standard keys list, in the Secret key row, click Reveal test key.
- Copy the key value by clicking it.
- Save the key value.
- 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.
You can't reveal a live mode secret key that you created
After you create a secret or restricted API key in live mode, we display the value before you save it. You must copy the value before saving it because you canât reveal it later. You can only reveal a default secret key or a key generated by a scheduled roll.
To reveal a secret or restricted key in live mode and attach a note:
Note
The API keys
link here opens in live mode.
- In the Developers Dashboard, select the API keys tab.
- In the Standard keys list or Restricted keys list, in the row for the key you want to reveal, click Reveal live key.
- Copy the key value by clicking it.
- Save the key value.
- Click Hide test key.
- Click the overflow menu () next to the key, then select Edit keyâ¦.
- In the Note field, enter the location where you saved the key, then click Save.
- If you created the key before Stripe introduced this feature, click Hide live key.
Note
Keys that you created before Stripe introduced this feature arenât automatically hidden when theyâre revealed. You must manually hide them.
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:
- Open the API keys page.
- In the row for the key you want to roll, click the overflow menu (), then select Roll keyâ¦.
- Choose an expiration date from the Expiration dropdown.
- Click Roll API key.
- The dialog displays the new key value. Copy it by clicking it.
- Save the key value. You canât retrieve it later.
- 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 Expiration, 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 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.
Note
You canât delete a publishable key.
To delete a key:
- In the Developers Dashboard, select the API keys tab.
- 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â¦.
- 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:
- Open the API keys page.
- Click Create secret key.
- 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 dialog. If the dialog doesnât continue automatically, click Continue.
- Enter a name in the Key name field.
- Click Create.
- The dialog displays the new key value. Copy it by clicking it.
- Save the key value. You canât retrieve it later.
- 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:
- Open the API keys page.
- 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.
- In the Key name field, enter a name. If you cloned an existing key, the default name is the cloned keyâs name.
- 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.
- Click Create key.
- 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 dialog. If the dialog doesnât continue automatically, click Continue.
- The dialog displays the new key value. Copy it by clicking it.
- Save the key value. You canât retrieve it later.
- 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:
Valid IP address ranges
You can specify any valid CIDR range. For example, a valid range could be 100.
, specified as 100.
. All addresses in the range must start with 100.
.
- Open the API keys page.
- 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â¦.
- Click Limit use to a set of IP addresses.
- 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.
- To add another address or range, click + Add.
- 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:
- Open the API keys page.
- In the row for the key you want to change, click the overflow menu (), then select Edit keyâ¦.
- If you want to change the name, in Key name, enter the new name.
- If you want to change the note text, in Note, enter the new note text.
- 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.