API keys
Stripe authenticates your API requests using your account’s API keys. If you don’t include your key when making an API request, or use an incorrect or outdated one, Stripe returns a 401 - Unauthorized HTTP response code. To learn more ways to manage your API keys, see Manage API keys.
Test and live modes overview
All Stripe API requests occur in either test or live mode. API objects in one mode (for example, product objects) aren’t accessible to the other.
| Type | When to use | Objects | How to use | Considerations |
|---|---|---|---|---|
| Test mode | Use this mode as you build your app. Payments are not processed by card networks or payment providers. | API calls return simulated account, payment, customer, charge, refund, transfer, balance, and subscription. | Use test credit cards and accounts. Don’t use actual payment authorizations, charges, or captures. | Identity doesn’t perform any verification checks. Connect account objects don’t return sensitive fields. |
| Live mode | Use this mode when you’re ready to launch your app. Card networks or payment providers process payments. | API calls return actual account, payment, customer, charge, refund, transfer, balance, and subscription objects. | Use valid credit cards and accounts. Use actual payment authorizations, charges, and captures for credit cards and accounts. | Disputes have a more nuanced flow and a simpler testing process. Some Sources payment methods have a more nuanced flow and require more steps. |
API keys
All accounts have a total of four keys: a publishable and secret key pair for test mode and live mode. Stripe APIs use your secret key to authenticate requests on your server. By default, your account’s secret keys can be used to perform any API request without restriction. You can find your keys on the API Keys page in the Developers Dashboard.
Stripe automatically populates code examples in our documentation with your test API keys while you’re logged in—only you can see these values. For your convenience, your test API keys for are:
| Type | Value | When to use |
|---|---|---|
| Publishable | pk_test_TYooMQauvdEDq54NiTphI7jx | On the client-side. Can be publicly-accessible in your web or mobile app’s client-side code (such as checkout.js) to tokenize payment information such as with Stripe Elements. By default, Stripe Checkout tokenizes payment information. |
| Secret | sk_test_4eC39HqLyjWDarjtT1zdp7dc | 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. |
Use only your test API keys for testing and development. This ensures that you don’t accidentally modify your live customers or charges.
If you don’t have an administrator or developer role, you may not have access to view your API keys in the Dashboard. Ask your Stripe account’s owner to add you to their team as a developer.
Reveal an API secret key for live mode (one time)
An API secret key for live mode is only visible the first time you access it. After that, the Dashboard no longer shows the secret key. Use these steps to reveal a secret key and leave a note that describes where it lives in your own systems.
- Open the API keys page.
- Click Reveal live key.
- In Notes, enter where your key lives in your own systems.
Keys created prior to the introduction of this feature are not automatically hidden when they are revealed, but can be hidden manually.
Revoke (“roll”) 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. Use these steps to revoke your API secret key and generate a new key.
- Open the API keys page.
- Click the three dots (…) next to your secret key, click Roll key.
- In Expiration, choose when to expire the existing key:
- now
- in 1 hour
- in 24 hours
- in 3 days
- in 7 days
- Click Roll API key.
The expiration period you choose blocks and expires the existing key for the time period you specify. Regardless of the expiration period, you can use the new key immediately.
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.
Limiting access with restricted API keys
A restricted API key allows only the minimum level of access that you specify. Restricted keys cannot interact with many parts of Stripe’s API and are intended to reduce risk when using or building microservices. They should not be used 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 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.
To create a restricted API key, see Manage API keys.