API keys

Use API keys to authenticate API requests.

Stripe authenticates your API requests using your account’s API keys. Stripe raises an invalid request error if you don’t include a key, and an authentication error if the key is incorrect or outdated.

You can use the Developers Dashboard to reveal, revoke, and create secret API keys. If you’re setting up Stripe through a third-party platform (3PP), reveal your API keys in live mode to begin processing payments.

Test mode versus live mode

All Stripe API requests occur in either test mode or live mode. API 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.

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 on the API keys page in the Developers Dashboard. We include randomly generated API keys in our code examples if you’re not logged in. Replace these with your own or log in to see code examples populated with your own test API keys. If you can’t view your API keys, ask your Stripe account’s owner to add you to their team with the proper permissions.

Type	Value	When to use
Secret		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		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.

Keep your keys safe

Your secret API key can be used to make any API call on behalf of your account, such as creating a charge or performing a refund. Use the following best practices to keep your keys safe:

Grant access only to those who need it.
Ensure the key is kept out of any version control system you might be using.
Control access to your key using a password manager or secrets management service.
Don’t embed your secret API key in mobile applications or other places from where the key could be extracted.

Restricted API keys

A restricted API key allows only the minimum level of access that you specify. Restricted keys can’t interact with many parts of Stripe’s API and are intended to reduce risk when using or building microservices. Don’t use restricted keys as an alternative to your account’s API keys during development of your Stripe integration.

Use restricted API keys if you’re working with microservices that interact with the Stripe API on your behalf. You can create restricted API keys in the Dashboard that limit access to, and permissions to specific account data. For example, you can create a restricted key that grants read-only access to dispute data, then use it with a dispute monitoring service.

Permission errors

If you use a restricted API key on a call it doesn’t have access to, Stripe raises a permission error.

Reveal an API secret key for test mode

Stripe APIs use your secret key to authenticate requests from your server. To find your API secret key for test mode:

Open the API keys page.
Under Standard keys, in the Secret key row, click Reveal test key and save the value.

Reveal your secret key in test mode

Reveal an API secret key for live mode

For security, Stripe only shows you an API secret key for live mode once. Store the key someplace safe where you won’t lose it. To help yourself remember where you stored it, you can leave a note in the Dashboard. If you do lose the key, you can revoke it and create another. Use these steps to reveal a secret key and attach a note:

Open the API keys page.
Click Reveal live key.
In Notes, write down your key’s location.

Note

Keys that you created before Stripe introduced this feature are not automatically hidden when they’re revealed. You must manually hide them.

Revoke an API secret key

If you’re in live mode and you lose your API secret key or API restricted key, you can’t recover it from the Dashboard. Similarly, if your secret key is compromised, you need to revoke (“roll”) the key to block any API requests that might use that key. The key stops working after the expiration date you choose. To revoke your API secret key and generate a new key:

Open the API keys page.
Click the overflow menu (…) next to your secret key, click Roll key.
In Expiration, choose when to expire the existing key.
Click Roll API key.

Create a new API secret key

To create a new API secret key in the Dashboard:

Open the API keys page.
Click Create secret key.
Enter a name in Key name.
Click Create.

Create a restricted API secret key

A restricted API key only allows the minimum level of access that you specify. To create a restricted API secret key:

Open the API keys page.
Click Create restricted key.
Enter a name in Key name.
Select the API resources and permissions for the key.
Click Create key.

Create a restricted API key