Get started with Stripe APIs
Every call to a Stripe API must include an API secret key. After you create a Stripe account, we generate two pairs of API keys for your Stripe user—a publishable client-side key and a secret server-side key—for both test and live modes. To start moving real money with your live-mode keys, you need to activate your account.
Initial setup
Click the Sign in button to login to the Stripe docs site, and start using your test mode API keys for authenticated requests.
Send your first API request
Start experimenting with Stripe APIs using the Stripe Shell, which lets you run Stripe CLI commands directly from the Stripe docs site. The Stripe Shell operates exclusively in test mode, so you don’t have to worry about creating any real transactions that move money.
To Create a customer using the Stripe Shell, enter the following command:
Command Linestripe customers create --email=jane.smith@email.com --name="Jane Smith" --description="My First Stripe Customer"If everything worked, the command-line displays the following response:
{ "id":, "object":"cus_LfctGLAICpokzr","customer"(Optional) Run the same command by passing in your API secret key for test mode:
Command Linestripe customers create --email=jane.smith@email.com --name="Jane Smith" --description="My First Stripe Customer" --api-key sk_test_4eC39HqLyjWDarjtT1zdp7dcIf everything worked, the command-line displays the following response:
{ "id":, "object":"cus_LfdZgLFhah76qf","customer"
View logs and events
When you call Stripe APIs, Stripe creates and stores API and Events objects for your Stripe user account. The API key you specify for the request determines whether the objects are stored in test or live mode. For example, the last request used your API secret key so Stripe stored the objects in test mode.
Store your API 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.
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. |