# Connect OAuth reference This reference lists available public methods for our OAuth endpoints for Connect. *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) platforms can work with three different [account types](https://docs.stripe.com/connect/accounts.md). The content on this page applies only to Standard accounts. The OAuth *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) flow allows you to customize the user’s experience by passing additional parameters to Stripe. Some common examples are explained below, and the rest of the reference lists every possible option. > As a platform, remember that data you create for a Standard account (that is, charges, customers, *invoices* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice), and so on) will be visible on their Stripe account. This also means if they connect other platforms, those platforms will have access to that data too. > > Starting in June 2021, Platforms using OAuth with `read_write` scope won’t be able to connect to accounts that are controlled by another platform. > > [Extensions](https://docs.stripe.com/building-extensions.md) won’t experience any changes to how OAuth behaves. Learn more about [OAuth changes for Standard Platforms](https://docs.stripe.com/connect/oauth-changes-for-standard-platforms.md). ## Common examples ### Prefill fields Provide the best possible user experience for users who need to create a new Stripe account by prefilling the account form fields with information you already have, like the user’s email and name. Prefilling has no effect if your user already has a Stripe account. You can’t prefill certain fields, including terms of service acceptance and RISA acceptance in Japan. ### Dynamically set the redirect URI For security purposes, Stripe redirects a user only to a predefined URI. However, Connect allows you to define more than one redirect URI, which you can use to further customize the user’s experience. For example, you could redirect some of your users back to **https://sub1.example.com** and others to **https://sub2.example.com**. To dynamically set the redirect URI: 1. In your [platform settings](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth), add each redirect URI. 1. Add a `redirect_uri` parameter to your authorization request and set the value to one of your redirect URIs. ``` https://connect.stripe.com/oauth/authorize?response_type=code&client_id={{CLIENT_ID}}&scope=read_write&redirect_uri=https://sub2.example.com ``` If no `redirect_uri` is specified in the URL, then Stripe uses the first URI configured in your platform settings. ## Authorize the account For Standard accounts: `GET https://connect.stripe.com/oauth/authorize` Sends the user to Stripe to connect to your platform. ### Request | Parameter | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `client_id` | The unique identifier provided to your application, found in your [application settings](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth). | | `response_type` | The only option at the moment is **code**. | | `redirect_uri`(Optional) | The URL for the authorize [response](https://docs.stripe.com/connect/oauth-reference.md#get-authorize-response) redirect. If provided, this must exactly match one of the comma-separated `redirect_uri` values in your [application settings](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth). To protect yourself from certain forms of man-in-the-middle attacks, the live mode `redirect_uri` must use a secure HTTPS connection. Defaults to the `redirect_uri` in your application settings if not provided. | | `scope`(Optional)(Standard Only) | **read\_write** or **read\_only**, depending on the level of access you need. Defaults to **read\_only** for Standard accounts. Note **read\_only** [can only be specified for extensions](https://docs.stripe.com/connect/oauth-changes-for-standard-platforms.md). | | `state`(Optional) | An arbitrary string value we’ll pass back to you, useful for CSRF protection. | The following query string parameters are all optional—we use them to prefill details in the account form for new users. Some prefilled fields (for example, URL or product category) might be automatically hidden. Any parameters with invalid values are silently ignored. Note that some of these parameters apply only to Standard accounts (indicated). | 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 can 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. It must be URL-encoded and include a scheme (**http** or **https**). If you prefill this field, include a description of the user’s products or services and their contact information in the linked page. 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 (for example, **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. | | `stripe_user[business_type]` | The type of the business. For Standard accounts, the value must be **sole\_prop**, **corporation**, **non\_profit**, **partnership**, or **llc**. | | `stripe_user[first_name]` | First name of the person filling out a Stripe application. | | `stripe_user[last_name]` | Last name of the person 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 filling out a Stripe application. If you choose to pass these parameters, you must pass all three. | | `stripe_user[street_address]`(Standard only) | Street address of the business. | | `stripe_user[city]`(Standard only) | Address city of the business. To prevent ambiguity, also prefill `stripe_user[country]` with the corresponding country. | | `stripe_user[state]`(Standard only) | Address state of the business. Must be the two-letter state or province code (for example, **NY** for a US business or **AB** for a Canadian one). Must also prefill `stripe_user[country]` with the corresponding country. | | `stripe_user[zip]`(Standard only) | Address postal code of the business. Must be a string. To prevent ambiguity, also prefill `stripe_user[country]` with the corresponding country. | | `stripe_user[physical_product]`(Standard only) | A string: **true** if the user sells a physical product, **false** otherwise. | | `stripe_user[product_description]` | A description of what the business is accepting payments for. | | `stripe_user[currency]`(Standard only) | Three-letter [ISO code](http://en.wikipedia.org/wiki/ISO_4217) representing currency, in lowercase (for example, **usd** or **cad**). Must be a valid country and currency combination that Stripe supports. Must prefill `stripe_user[country]` with the corresponding country. | | `stripe_user[first_name_kana]` | The Kana variation of the first name of the person filling out a Stripe application. Must prefill `stripe_user[country]` with **JP**, as this parameter is only relevant for Japan. | | `stripe_user[first_name_kanji]` | The Kanji variation of the first name of the person filling out a Stripe application. Must prefill `stripe_user[country]` with **JP**, as this parameter is only relevant for Japan. | | `stripe_user[last_name_kana]` | The Kana variation of the last name of the person filling out a Stripe application. Must prefill `stripe_user[country]` with **JP**, as this parameter is only relevant for Japan. | | `stripe_user[last_name_kanji]` | The Kanji variation of the last name of the person filling out a Stripe application. Must prefill `stripe_user[country]` with **JP**, as this parameter is only relevant for Japan. | | `stripe_user[gender]` | The gender of the person filling out a Stripe application. (International regulations require either **male** or **female**.) Must prefill `stripe_user[country]` with **JP**, as this parameter is only relevant for Japan. | | `stripe_user[block_kana]`(Standard only) | The Kana variation of the address block. This parameter is only relevant for Japan. You must prefill `stripe_user[country]` with **JP** and `stripe_user[zip]` with a valid Japanese postal code to use this parameter. | | `stripe_user[block_kanji]`(Standard only) | The Kanji variation of the address block. This parameter is only relevant for Japan. You must prefill `stripe_user[country]` with **JP** and `stripe_user[zip]` with a valid Japanese postal code to use this parameter. | | `stripe_user[building_kana]`(Standard only) | The Kana variation of the address building. This parameter is only relevant for Japan. You must prefill `stripe_user[country]` with **JP** and `stripe_user[zip]` with a valid Japanese postal code to use this parameter. | | `stripe_user[building_kanji]`(Standard only) | The Kanji variation of the address building. This parameter is only relevant for Japan. You must prefill `stripe_user[country]` with **JP** and `stripe_user[zip]` with a valid Japanese postal code to use this parameter. | ### Response The user’s browser is redirected back to your [configured redirect URI](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth) or the value you passed in the `redirect_uri` parameter. When successful, you 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 won’t 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](https://docs.stripe.com/connect/oauth-reference.md#get-authorize-error-codes) 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 an invalid URL or isn’t allowed by your [application settings](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth). | | `invalid_request` | Missing `response_type` parameter. | | `unsupported_response_type` | Unsupported `response_type` parameter. Currently the only supported `response_type` is **code**. | ## Complete the connection and get the account ID `POST https://connect.stripe.com/oauth/token` Used both for turning an `authorization_code` into an account connection, and for getting a new access token using a `refresh_token`. ### Request Make this call using your secret API key as a `client_secret` POST parameter: #### curl ```bash curl https://connect.stripe.com/oauth/token \ -u <>: \ -d "code"="ac_123456789" \ -d "grant_type"="authorization_code" ``` When converting an authorization code to an access token, you must use an API key that matches the mode—live or test—of the authorization code (which depends on whether the `client_id` used was production or development). When using a refresh token to request an access token, you can 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 mode—live or test—is revoked. > Per OAuth v2, this endpoint isn’t idempotent. Consuming an authorization code more than once revokes the account connection. | 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. | ### Response | Parameter | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scope` | The scope granted to the access token, depending on the scope of the authorization code and `scope` parameter. | | `stripe_user_id` | The unique ID of the account you’ve been granted access to, as a string. | | `livemode` | Indicates whether the platform’s access to perform updates on behalf of the connected account includes livemode access, or is limited to testmode actions. This matches the livemode of the application used [to authorize the OAuth request](https://docs.stripe.com/connect/oauth-reference.md#get-authorize). | | `token_type` | Always has a value of **bearer**. | | `access_token` | (Deprecated) Use the `Stripe-Account` [header](https://docs.stripe.com/connect/authentication.md#stripe-account-header) with your platform’s secret key (that can make requests on behalf of this Stripe account). | | `stripe_publishable_key` | (Deprecated) Use the `Stripe-Account` [header](https://docs.stripe.com/connect/authentication.md#stripe-account-header) with your platform’s publishable key (that can make requests on behalf of this Stripe account). | | `refresh_token` | (Deprecated) Can be used to get a new access token of an equal or lesser scope, or of a different live mode (where [applicable](https://docs.stripe.com/connect/testing.md#creating-accounts)). | ### Error Response | Parameter | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------- | | `error` | A unique [error code](https://docs.stripe.com/connect/oauth-reference.md#post-token-error-codes) 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` doesn’t exist, is expired, has been used, or doesn’t belong to you - `refresh_token` doesn’t exist or doesn’t belong to you - API key mode (live or test key) doesn’t 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**. | #### API ## Revoke the account’s access `POST https://connect.stripe.com/oauth/deauthorize` Used for revoking access to an account. After revocation, the account can’t be accessed by your platform in the Dashboard or through the API. The account can continue to access its own data and functionality through the account’s Dashboard. > You can only revoke a Standard account’s access to your platform. ### Request Make this call using your secret API key as an Authorization header. #### curl ```bash curl https://connect.stripe.com/oauth/deauthorize \ -u <>: \ -d client_id="ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb" \ -d stripe_user_id=acct_ON3nXtRQkhmUIQ ``` When revoking access to an account, you must use an API key that matches the mode (live or test) used to connect to the account. Use a live mode API key if a production `client_id` created the connection, or a test API key if a development `client_id` created it. | 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 is successful. | ### Error Response | Parameter | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `error` | A unique [error code](https://docs.stripe.com/connect/oauth-reference.md#post-deauthorize-error-codes) per error type. | | `error_description` | A human readable description of the error. | ### Error Codes | 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` doesn’t belong to you - `stripe_user_id` doesn’t exist or isn’t connected to your application - API key mode (live or test key) doesn’t match the `client_id` mode - `no_deauth_on_controlled_account` the account can’t be disconnected and instead use the [rejection API](https://docs.stripe.com/api/account/reject.md). | #### Dashboard ### Removing accounts through the Dashboard You can disconnect a connected account from its account details page in your Dashboard. Click the overflow menu (⋯) on the top right of the page, then select **Remove account**. This action disconnects the account from your platform and revokes access in the same way as the OAuth de-authorize endpoint. Removing an account from your platform also permanently resets all platform controls on the account, such as payout timing, even if the account reconnects later. It doesn’t otherwise affect the account, which still functions as a normal Stripe account.