API keys
Manage your API keys to authenticate requests with Stripe.
Stripe authenticates your API requests using your account’s API keys. If you do not include your key when making an API request, or use one that is incorrect or outdated, Stripe returns an error.
Every account is provided with separate keys for testing and for running live transactions. All API requests exist in either test or live mode, and objects—customers, plans, coupons, and so forth—in one mode cannot be manipulated by objects in the other.
There are also two types of API keys: publishable and secret.
- Publishable API keys are meant solely to identify your account with Stripe, they aren’t secret. In other words, they can safely be published in places like your Stripe.js JavaScript code, or in an Android or iPhone app. Publishable keys only have the power to create tokens.
- Secret API keys should be kept confidential and only stored on your own servers. Your account’s secret API key can perform any API request to Stripe without restriction.
Each account has a total of four keys: a publishable and secret key pair for test mode and live mode.
Obtaining your API keys
Your API keys are available in the Dashboard. We include randomly generated API keys in our code examples if you are not logged in. Replace these with your own or log in to see code examples populated with your own test API keys.
If you don’t have an administrator or developer role, you may not have access to view your API keys in the Dashboard. Contact your Stripe account’s owner and ask to be added to their team as a developer.
Test and live modes
The test and live modes function almost identically, with a few necessary differences:
- In test mode, payments are not processed by card networks or payment providers, and only our test payment information can be used.
- Some payment methods using Sources have a more nuanced flow in live mode, with more steps required than those in test mode.
- Disputes also have a more nuanced flow in live mode, and a simpler testing process.
- Webhooks that were not successfully acknowledged are retried three times over a few hours (as opposed to 72 hours for live mode).
Keeping your keys safe
Your secret API key can be used to make any API call on behalf of your account, such as creating charges or performing refunds. Treat your secret API key as you would any other password. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using. Control access to your key using a password manager or secrets management service.
In live mode, new secret keys are only visible the first time you access them. After that, the Dashboard redacts the API key. When the key is revealed, you can leave a note on the Dashboard describing the location on your own systems where you’ve copied it. If you lose your secret key, you can’t recover it from the Dashboard and must roll the key or create another one.
Displaying the note for a secret key that has been redacted.
Rolling keys
If an API key is compromised, roll the key in the Dashboard to block it and generate a new one.
Rolling an API key.
When rolling an API key, you can choose to block the old key immediately or allow it to work for 12 hours, providing you with time to make the transitions. In either case, the new key can be used immediately.
Limiting access with restricted API keys
Your account’s secret API keys can be used to perform any API request without restriction. For greater security, you can create restricted API keys that limit access to, and permissions for, different areas of your account data. These take the place of your secret API key and should be used if you’re working with microservices that interact with the Stripe API on your behalf.
A restricted key allows only the minimum level of access that the service needs while protecting account data it doesn’t need. For example, you can create a restricted key that grants read-only access to dispute data, then use it with a dispute monitoring service.
If you no longer need a restricted key (or you suspect it has been compromised), you can revoke it at any time. You can also edit the key to change its level of access.
Restricted keys are intended to reduce the risk when using or building microservices. They are not to be used as an alternative to your account’s API keys during development of your Stripe integration—restricted keys cannot interact with many parts of Stripe’s API. Use your test API keys during development and live API keys once your integration is live.