Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Developer tools
    Get started
    Quickstarts
    Stripe Shell
    Stripe CLI
    Dashboard
    Stripe for Visual Studio Code
    Webhooks
    File uploads
    Error handling
    Security at Stripe
    API
    API keys
    Upgrades
    Changelog
    Rate limits
    Automated testing
    Data Availability
    Expanding responses
    Domains and IP addresses
    Search
    Building With Stripe
    Prebuilt iOS UI
    Prebuilt Android UI
    Extensions
    Samples
    Checklist
    Feedback
SDKs
Sample projects
Videos
Stripe Apps
Stripe Connectors
Partners
HomeDeveloper tools

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 and live modes

All Stripe API requests occur in either test 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 useObjectsHow to useConsiderations
test modeUse this mode as you build your app. In test mode, card networks and payment providers don’t process payments.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 Accounts objects don’t return sensitive fields.
live modeUse this mode when you’re ready to launch your app. In live mode, card networks and payment providers do 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 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:

  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.
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
SecretOn 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.
PublishableOn 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:

  1. Open the API keys page.
  2. Under Standard keys, in the Secret key row, click Reveal test key and save the value.
Reveal your secret key in test mode

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:

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

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:

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

Create a new API secret key

To create a new API secret key in the Dashboard:

  1. Open the API keys page.
  2. Click Create secret key.
  3. Enter a name in Key name.
  4. 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:

  1. Open the API keys page.
  2. Click Create restricted key.
  3. Enter a name in Key name.
  4. Select the API resources and permissions for the key.
  5. Click Create key.
Create a resticted API key

Create a restricted API key

Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Test and live modes
Secret and publishable keys
Reveal an API secret key for test mode
Reveal an API secret key for live mode
Revoke an API secret key
Create a new API secret key
Create a restricted API secret key
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$