Integrating OAuth

This tutorial will help you integrate the Stripe Connect OAuth flow into your application. If you need help, check out our answers to common questions or chat live with our developers in #stripe on freenode.

This tutorial assumes you have already registered an application

Stripe Connect supports the OAuth 2.0 protocol. Once your users connect with Stripe, your application will be able to make API requests on their behalf without requiring their user credentials or API keys.

How it works

When a user on your site wants to connect with Stripe, you'll send them to us with your application's client_id. They'll be prompted to connect their Stripe account, and afterwards, we will redirect them back to your redirect_uri with an authorization code or an error (if the authorization was denied).

You can then trade that authorization code for an access_token by making a request to our OAuth token endpoint. An access_token can be used as a Stripe API key.


Implementing the flow

The relevant Stripe endpoints are:

  • authorize_url: https://connect.stripe.com/oauth/authorize
  • access_token_url: https://connect.stripe.com/oauth/token

The redirect_uri is an endpoint configured in your application settings; we will redirect the user and pass the authorization code there after authorization. You may also specify a comma-separated list of allowed redirect uri's in your application settings and pass a redirect_uri parameter to your authorize request.

Application Settings

You can find your client_ids and edit details like your application name, url, logo, and redirect_uri in your application settings.

Here, your users will also be able to view connected applications with their respective permission levels and revoke application authorizations.

Connecting users

When you're ready to have your users connect with Stripe, show a Stripe Connect button that sends them to our authorize_url endpoint:

https://connect.stripe.com/oauth/authorize?response_type=code&client_id=ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7&scope=read_write&state=1234

For example:

Connect with Stripe

There are a couple of special parameters you can use here:

  • state: We'll pass this parameter back to you on redirect (useful for CSRF protection or identifying users)
  • stripe_landing: Determines whether to show a login screen or account application by default. If you're assuming your users will already have existing Stripe accounts, you should pass in stripe_landing=login.

We'll prompt the user to allow or deny your application, then send them back to your redirect_uri along with the authorization code:

HTTP/1.1 302 Found
Location: https://stripe.com/connect/default/oauth/test?scope=read_write&state=1234&code=AUTHORIZATION_CODE

Or, if the authorization was denied, we'll include an error instead:

HTTP/1.1 302 Found
Location: https://stripe.com/connect/default/oauth/test?error=access_denied&error_description=The%20user%20denied%20your%20request

For more details on the redirect parameters, see the reference guide.

After the user has connected

Using the code parameter we sent back to your redirect_uri endpoint, you should make a POST request to our access_token_url endpoint:

curl -X POST https://connect.stripe.com/oauth/token \
  -d client_secret=sk_test_BQokikJOvBiI2HlWgH4olfQ2 \
  -d code=AUTHORIZATION_CODE \
  -d grant_type=authorization_code

Note that you'll make the request with your live secret API key or test secret API key, depending on whether you want to get a live or test access token back. Stripe will return a response containing the access_token or an error.

{
  "token_type": "bearer",
  "stripe_publishable_key": PUBLISHABLE_KEY,
  "scope": "read_write",
  "livemode": "false",
  "stripe_user_id": USER_ID,
  "refresh_token": REFRESH_TOKEN,
  "access_token": ACCESS_TOKEN
}
{
  "error": "invalid_grant",
  "error_description": "Authorization code does not exist: AUTHORIZATION_CODE"
}

You're done! You can now use this access_token as you would normally use a Stripe secret API key:

curl https://api.stripe.com/v1/charges \
  -u ACCESS_TOKEN: \
  -d amount=400 \
  -d currency=usd \
  -d description=Charge for you@stripe.com \
  -d card=TOKEN_ID

You'll notice that the response also includes a refresh_token, which you can use to generate test access tokens for a production client_id or to roll your access token. You should hold on to this, as you're only able to get it with this first POST.

Using access tokens

When using our official API libraries, we recommend that you pass in the access_token with every request, instead of setting the API key globally. This is because the access_token used in any API request depends on the user you're charging on behalf of.

Generating test keys for livemode applications

You may generate only test access tokens using a development client_id, but may generate either live or test access tokens using a production client_id.

If you want to generate test access tokens for a production client_id, you can do so using a refresh_token:

curl -X POST https://connect.stripe.com/oauth/token \
  -d client_secret=sk_test_BQokikJOvBiI2HlWgH4olfQ2 \
  -d refresh_token=REFRESH_TOKEN \
  -d grant_type=refresh_token

Publishable keys

Don't forget that when using Stripe.js (required for all applications), you'll need to provide the stripe_publishable_key returned in the OAuth response, not your own publishable key.

Any token generated by a publishable key will only be usable by that account—that is, you won't be able to make a charge using a token created by someone else's publishable key. The only exception to this rule is if you're sharing customers.


Sample OAuth Applications

Here's some sample code, but we recommend that you use a client library instead of handling the implementation yourself.