Connect OAuth Reference

This reference lists available public methods for our OAuth endpoints. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

GET https://connect.stripe.com/oauth/authorize

Request

Parameter	Description
`client_id`	The unique identifier provided to your application, found in your application settings.
`response_type`	The only option at the moment is `code`.
`redirect_uri`Optional	The URL for the authorize response redirect. If provided, this must exactly match one of the comma-separated `redirect_uri` values in your application settings. In order to protect yourself from certain forms of man-in-the-middle attacks, we require that the livemode `redirect_uri` are secure HTTPS connections. This means that any livemode `redirect_uri` must start with `https://` rather than just `http://`. Defaults to the `redirect_uri` in your application settings if not provided.
`scope`Optional	`read_write` or `read_only`, depending on the level of access you need. Defaults to `read_only`.
`state`Optional	An arbitrary string value we will pass back to you, useful for CSRF protection.
`stripe_landing`Optional	`login` or `register`, depending on what type of screen you want your users to see. You should only override this to be `login` if you expect all of your users to have Stripe accounts already (e.g. most read-only applications, like analytics dashboards or accounting software). Defaults to `login` for scope `read_only` and `register` for scope `read_write`.
`always_prompt`Optional	Boolean to indicate that the user should always be asked to connect, even if they're already connected. Defaults to `false`.

The following query string parameters are all optional; we will use them to prefill details in the account form for new users. Some prefilled fields (e.g. URL or product category) may be automatically hidden from the user's view. Any parameters with invalid values will silently be ignored.

Parameter	Description
`stripe_user[email]`Recommended	The user's email address. Must be a valid email format.
`stripe_user[url]`Recommended	The URL for the user's business. This may be the user's website, a profile page within your application, or another publicly available profile for the business, such as a LinkedIn or Facebook profile. Must be URL-encoded and include a scheme (`http` or `https`). If you will be prefilling this field, we highly recommend that the linked page contain a minimum of a description of the user's products or services and contact information. If we don't have enough information, we'll have to reach out to the user directly before initiating payouts.
`stripe_user[country]`	Two-letter country code. E.g. "US" or "CA". Must be a country that Stripe currently supports.
`stripe_user[phone_number]`	The business phone number. Must be 10 digits only. Must also prefill `stripe_user[country]` with the corresponding country.
`stripe_user[business_name]`	The legal name of the business, also used for the statement descriptor.
`stripe_user[business_type]`	The type of the business. Must be one of `sole_prop`, `corporation`, `non_profit`, `partnership`, or `llc`.
`stripe_user[first_name]`	First name of the person who will be filling out a Stripe application.
`stripe_user[last_name]`	Last name of the person who will be filling out a Stripe application.
`stripe_user[dob_day]` `stripe_user[dob_month]` `stripe_user[dob_year]`	Day (`0`-`31`), month (`1`-`12`), and year (`YYYY`, greater than 1900) for the birth date of the person who will be filling out a Stripe application. All three are required.
`stripe_user[street_address]`	Street address of the business.
`stripe_user[city]`	Address city of the business. We highly recommend that you also prefill `stripe_user[country]` with the corresponding country.
`stripe_user[state]`	Address state of the business. Must be the two-letter state or province code, e.g. "NY" for a U.S. business or 'AB' for a Canadian one. Must also prefill `stripe_user[country]` with the corresponding country.
`stripe_user[zip]`	Address ZIP code of the business. Must be a string. We highly recommend that you also prefill `stripe_user[country]` with the corresponding country.
`stripe_user[physical_product]`	`true` if the user sells a physical product, `false` otherwise, as a string.
`stripe_user[shipping_days]`	Only used if the user sells a physical product, an integer that represents the average number of days it takes this business to ship a product.
`stripe_user[product_category]`	The type of product this business deals with. Should be one of these values: `art_and_graphic_design` `advertising` `charity` `clothing_and_accessories` `consulting` `clubs_and_membership_organizations` `education` `events_and_ticketing` `food_and_restaurants` `software` `professional_services` `tourism_and_travel` `web_development` `other`
`stripe_user[product_description]`	A description of what the business is accepting payments for.
`stripe_user[average_payment]`	Average amount per payment for the business. Must be an integer (in dollars), e.g. 10000 for $10,000.
`stripe_user[past_year_volume]`	The estimated past year's volume for the business. Must be an integer (in dollars), e.g. 10000 for $10,000.
`stripe_user[currency]`	Three-letter ISO code representing currency. E.g. "usd" or "cad". Must be a valid country/currency combination that Stripe supports. Must prefill `stripe_user[country]` with the corresponding country.

Response

The user's browser will be redirected back to your configured redirect URI or the value you passed in the redirect_uri parameter. When successful, you should receive the following query parameters:

Parameter	Description
`code`	An authorization code you can use in the next call to get an access token for your user. This can only be used once and expires in 5 minutes.
`scope`	`read_write` or `read_only`, depending what you passed on the initial GET request.
`state`	The value of the `state` parameter you provided on the initial GET request.

Error Response

In case of an error, the user's browser will not be redirected except in the case of access_denied. Instead, errors will be returned in a JSON dictionary with the following fields:

Parameter	Description
`error`	A unique error code per error type.
`error_description`	A human readable description of the error.
`state`	The value of the `state` parameter you provided on the initial GET request.

Error Codes

Parameter	Description
`access_denied`	User denied authorization.
`invalid_scope`	Invalid `scope` parameter provided.
`invalid_redirect_uri`	Provided `redirect_uri` parameter is either an invalid URL or is not allowed by your application settings.
`invalid_request`	Missing `response_type` parameter.
`unsupported_response_type`	Unsupported `response_type` parameter. Currently the only supported `response_type` is `code`.

POST https://connect.stripe.com/oauth/token

This endpoint is used both for turning an authorization_code into an access_token, and for getting a new access token using a refresh_token.

Request

This call should be made using your secret API key as a client_secret POST parameter:

curl https://connect.stripe.com/oauth/token \
   -d client_secret="{SECRET_API_KEY}"

When requesting an access token from an authorization code, you must use an API key that matches the livemode of the authorization code (which depends on whether the client_id used was production or development).

When requesting an access token from a refresh token, you may use either a test or live API key to obtain a test or live access token respectively. Any existing access token with the same scope and livemode will be revoked.

Parameter Description

Parameter	Description
`grant_type`	`authorization_code` when turning an authorization code into an access token, or `refresh_token` when using a refresh token to get a new access token.
`code` OR `refresh_token`	The value of the `code` or `refresh_token`, depending on the `grant_type`.
`scope`Optional	When requesting a new access token from a refresh token, any scope that has an equal or lesser scope as the refresh token. Has no effect when requesting an access token from an authorization code. Defaults to the scope of the refresh token.

grant_type

authorization_code when turning an authorization code into an access token, or refresh_token when using a refresh token to get a new access token.

code OR refresh_token

The value of the code or refresh_token, depending on the grant_type.

scopeOptional

When requesting a new access token from a refresh token, any scope that has an equal or lesser scope as the refresh token. Has no effect when requesting an access token from an authorization code.

Defaults to the scope of the refresh token.

Response

Parameter	Description
`access_token`	The access token you can use to make requests on behalf of this Stripe account. Use it as you would any Stripe secret API key. This key does not expire, but may be revoked by the user at any time (you'll get a `account.application.deauthorized` webhook event when this happens).
`scope`	The scope granted to the access token, depending on the scope of the authorization code and `scope` parameter.
`livemode`	The livemode of the token. If `true`, the `access_token` can be used as a live secret key. If `false`, the `access_token` can be used as a test secret key. Depends on the livemode of the secret API key used to make the request.
`token_type`	Will always have a value of `bearer`.
`refresh_token`	Can be used to get a new access token of an equal or lesser scope, or of a different livemode (where applicable).
`stripe_user_id`	The unique id of the account you have been granted access to, as a string.
`stripe_publishable_key`	A publishable key that can be used with this account. Matches the livemode of the token.

Error Response

Parameter	Description
`error`	A unique error code per error type.
`error_description`	A human readable description of the error.

Error Codes

Parameter	Description
`invalid_request`	No `code`, `refresh_token` or `grant_type` parameter provided (where required).
`invalid_grant`	A variety of things can prompt this error: `code` does not exist, is expired, has been used, or does not belong to you. `refresh_token` does not exist or does not belong to you. API key mode (live or test mode) does not match the `code` or `refresh_token` mode
`unsupported_grant_type`	Unsupported `grant_type` parameter specified. The only currently supported types are `authorization_code` and `refresh_token`.
`invalid_scope`	Invalid `scope` parameter provided.
`unsupported_response_type`	Unsupported `response_type` parameter. Currently the only supported `response_type` is `code`.

POST https://connect.stripe.com/oauth/deauthorize

This endpoint is used for choosing to revoke access to an account.

Request

This call should be made using your secret API key as an Authorization header.

When revoking access to an account, you must use an API key that matches the livemode of the authorization code (which depends on whether the client_id used was production or development).

Parameter	Description
`client_id`	The `client_id` of the application that you'd like to disconnect the account from. The account must be connected to this application.
`stripe_user_id`	The account you'd like to disconnect from.

Response

Parameter	Description
`stripe_user_id`	The unique id of the account you have revoked access to, as a string. This is the same as the `stripe_user_id` you passed in. If this is returned, the revocation was successful.

Error Response

Parameter	Description
`error`	A unique error code per error type.
`error_description`	A human readable description of the error.

Error Codes

Parameter Description

Parameter	Description
`invalid_request`	No `client_id` or `stripe_user_id` parameter provided (where required).
`invalid_client`	A variety of things can prompt this error: `client_id` does not belong to you. `stripe_user_id` does not exist or is not connect to your application. API key mode (live or test mode) does not match the `client_id` mode.

invalid_request

No client_id or stripe_user_id parameter provided (where required).

invalid_client

A variety of things can prompt this error:

client_id does not belong to you.
stripe_user_id does not exist or is not connect to your application.
API key mode (live or test mode) does not match the client_id mode.