> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 23a6c2bb-6677-49ad-a21f-94fa443fd908
---
# Understand app installation flow with the option for partner sign in
> Review the updated installation flow of apps with and without partner sign in features turned on.
After October 26, 2026, all apps listed on the HubSpot Marketplace that wish to make changes to the app listing will be required to use an installation flow that includes an option to authenticate using [OAuth](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) without a separate partner sign in. You can choose to opt your app into this flow early, but once you do so, that app will be required to use that flow moving forward.
If installing your app requires the user to log in to an account in your system, it's recommended to authenticate with partner sign in. If you don't need the user to authenticate beyond using OAuth, you can authenticate without partner sign in.
## Understand limits and considerations
The updated install flow only applies to:
* Apps that have opted into using the updated install flow early. After October 26, 2026, it will apply to all apps that make changes in the listing editor.
* Apps listed on the HubSpot Marketplace.
* Customers installing the app for the first time. Existing customers who have already installed the app are not affected.
* Installs initiated from the HubSpot Marketplace. Installs initiated from external websites or the app itself are not affected.
* The option of whether customers need to sign in with an external system to authenticate. OAuth authentication itself is not affected.
* The app's installation process once you publish changes in the listing editor. Until then, the app's current installation process will not change.
## Opt into the updated install flow early
You can choose to switch to the updated install flow from the listing editor. Once in the new flow, you can specify a redirect URL and whether the app will require partner sign in.
1. In your HubSpot account, navigate to **Development**. In the left sidebar menu, click **App Listings**.
2. Hover over an app, then click the **More** dropdown menu and select **Edit draft**.
3. In the *Listing info* section, click **Enable seamless install flow**.
4. In the dialog box, select the **checkbox** that shows you understand you can't return to the previous install flow, then click **Enable seamless install**.
5. In the *Listing info* section of the listing editor, click the **Install button URL** dropdown menu and select a **URL**.
6. In the *Sign-in configuration* section, select whether the app will include partner sign in.
## Understand the install flow without partner sign in
### Developer perspective
Your install URL endpoint receives a request with these parameters:
* `code`: authorization code for completing the installation.
* `returnUrl`: URL used to direct the user back to HubSpot after installation completes. The `returnUrl` will be added as a query parameter to the end of the Redirect URL selected in the listing editor when HubSpot redirects the customer there.
* `step`: always set to `finalize`. You do not need to do anything with this parameter.
Once you receive the request, you should:
* Get the `code` and `returnUrl` from the URL parameters.
```javascript theme={null}
// Helper function
function getQueryParam(param) {
const params = new URLSearchParams(window.location.search);
return params.get(param);
}
const code = getQueryParam('code');
const returnUrl = getQueryParam('returnUrl');
```
* Use the provided `code` to [complete token exchange for OAuth](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).
* Required and optional scopes are already included in the install URL. If you need to use conditional scopes, you'll need to initiate a separate secondary install flow.
* Store any necessary configuration data associated with the user's HubSpot account.
Redirect the user back to the `returnUrl` provided in the installation request. Redirecting back to HubSpot is required to avoid an infinite login loop.
To avoid issues with the install flow, ensure that the endpoint handling the install flow can be framed by HubSpot in an embedded browser context.
For example, if you use a Content Security Policy, it should allow HubSpot as a frame ancestor:
`Content-Security-Policy: frame-ancestors 'self' https://app.hubspot.com https://app-eu1.hubspot.com;`
### Customer perspective
1. In your HubSpot account, click the **marketplace icon** in the top navigation bar, then select **HubSpot Marketplace**.
2. Click an **app card**.
3. In the top left, click **Install**.
4. In the dialog box, review the app's requirements, then select the **checkbox** and click **Connect app**.
5. Once the app is installed, you can start using the app:
* Click **Explore app features** to start from the Feature Discovery section of the app overview page in your Connected Apps settings.
* Click **Customize app cards** to start customizing the app's [app cards](https://knowledge.hubspot.com/integrations/install-and-manage-app-cards).
* Click the **X** in the top right to return to the app listing page.
## Understand the install flow with partner sign in
### Developer perspective
Your install URL endpoint receives a request with these parameters:
* `step=authorize`: indication that this is the initial step in the installation process.
* `returnUrl`: URL used to direct the user back to HubSpot after the authentication process completes. The `returnUrl` will be added as a query parameter to the end of the Redirect URL selected in the listing editor when we redirect the customer there.
* Example URL:
```
https://www.myinstallserver.com/install?returnUrl=https://hubspotreturnurl/install-success&step=authorize
```
* Get the `step` and `returnUrl` from the URL parameters, then show a login form or page to authenticate the user.
```javascript theme={null}
// Helper function
function getQueryParam(param) {
const params = new URLSearchParams(window.location.search);
return params.get(param);
}
const step = getQueryParam('step');
const returnUrl = getQueryParam('returnUrl');
```
Once the user has authenticated, you should:
* Generate a cryptographically secure, randomized token unique to this user. This is the `state` token used in future steps.
* For example:
```javascript theme={null}
function generateStateParameter() {
const array = new Uint8Array(32);
crypto.getRandomValues(array);
return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('');
}
const state = generateStateParameter();
```
* One option is to create a data table without RLS that stores the user's `uid` from your system and the `state` token.
* If you are using cookies, tag the cookies with *SameSite=none*.
* For security, it's recommended to have a `state` token with a relatively short expiration window, such as 10 minutes.
* Required and optional scopes are already present in the install URL.
* If you need to specify conditional scopes, it's recommended to include them in the `scope` query parameter. You can add scopes to this parameter as a list of scope names, separated by spaces.
* Add the `state` token you generated in the previous step to the `returnUrl` as a query parameter, as well as the `scope` parameter if you're using it, then redirect the user back to HubSpot. The redirect will look like this: `${returnUrl}?state=${state}`. Redirecting back to HubSpot is necessary to avoid an infinite login loop.
* For example:
```javascript theme={null}
const returnUrlObj = new URL(returnUrl);
// Set state token and conditional scopes
const scopes = [
'crm.objects.contacts.write',
'crm.objects.companies.read',
'crm.objects.companies.write'
]
returnUrlObj.searchParams.set('state', state);
returnUrlObj.searchParams.set('scope', scopes.join(' '));
// Redirect back to HubSpot
window.location.href = returnUrlObj.toString();
// e.g. returnUrlObj.toString() = "https://www.hubspotReturnUrl.com?state=123abc"
// or returnUrlObj.toString() = "https://www.hubspotReturnUrl.com?someHubSpotParam=returnUrlParam&state=123abc"
```
Your install URL endpoint receives a request with these parameters:
* `step=finalize`: indication that this is the final step in the installation process.
* `code`: the OAuth code HubSpot uses to generate your tokens.
* `state`: the secure token you generated in Step 3.
* `returnUrl`: URL used to direct the user back to HubSpot after the authentication process completes.
For example:
```
https://www.myinstallserver.com/install?code=123&state=30q94q3043&returnUrl=https://hubspotreturnurl/install-success&step=finalize
```
* Get the `step`, `code`, `state`, and `returnUrl` parameters from the URL.
```javascript theme={null}
// Helper function
function getQueryParam(param) {
const params = new URLSearchParams(window.location.search);
return params.get(param);
}
const step = getQueryParam('step');
const code = getQueryParam('code');
const state = getQueryParam('state');
const returnUrl = getQueryParam('returnUrl');
```
* Validate that the `state` token matches the original authentication request.
* Retrieve the associated user account.
* If you are able to verify the `state` token, complete the installation:
* Exchange the `code` for [OAuth access and refresh tokens](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).
* Redirect the customer to the `returnUrl`. Without this step, the user will be stuck in an infinite login loop.
* If you are not able to verify the `state` token, do not complete the installation.
* Redirect the customer to the `returnUrl`. Without this step, the user will be stuck in an infinite login loop.
To avoid issues with the install flow, ensure that the endpoint handling the install flow can be framed by HubSpot in an embedded browser context.
For example, if you use a Content Security Policy, it should allow HubSpot as a frame ancestor:
`Content-Security-Policy: frame-ancestors 'self' https://app.hubspot.com https://app-eu1.hubspot.com;`
### Customer perspective
1. In your HubSpot account, click the **marketplace icon** in the top navigation bar, then select **HubSpot Marketplace**.
2. Click an **app card**.
3. In the top left, click **Install**.
4. In the dialog box, click **Sign in** to sign up or log in to the app.
5. In the new window, finish the app's sign up / log in process externally.
6. After being redirected back to HubSpot, review the app's requirements, then select the **checkbox** and click **Connect app**.
7. Once the app is installed, you can start using the app:
* Click **Explore app features** to start from the Feature Discovery section of the app overview page in your *Connected Apps* settings.
* Click **Customize app cards** to start customizing the app's [app cards](https://knowledge.hubspot.com/integrations/install-and-manage-app-cards).
* Click the **X** in the top right to return the app listing page.
## Preview the install flow
Once you have opted into using the new install flow, you can test the installation process from the listing editor before publishing your changes:
1. In your HubSpot account, navigate to **Development**. In the left sidebar menu, click **App Listings**.
2. Hover over an app, then click the **More** dropdown menu and select **Edit draft**.
3. In the top right, click **Preview**.
4. Run through a test version of the installation process.
## Request an exemption
If you need to update your app listing but your app cannot support self-service installation due to complex technical onboarding or specific legal constraints, you can file an exemption request. These requests are reviewed individually by HubSpot's Eco Quality team, typically within 7-10 business days.
If the request is approved, this would allow your app to replace the mandatory *Install App* button with an option to contact you or book a meeting. If the request is denied, the app will have to use the *Install App* button required by the new install flow.
1. [Opt into the updated install flow](#opt-into-the-updated-install-flow-early).
2. In your HubSpot account, navigate to **Development**. In the left sidebar menu, click **App Listings**.
3. Hover over an app, then click the **More** dropdown menu and select **Edit draft**.
4. In the listing editor, click **Request removal** in the *Request to remove install button from your listing* section.
5. In the exemption request form, enter your name, email address, and company name, then click **Next**.
6. Enter your **Production app ID**.
7. Select an **app listing status**:
* **Listed**: your app listing is live on the *HubSpot Marketplace*.
* **Draft**: your app listing has been drafted, but isn't yet live.
8. Enter your **App Name**, then click **Next**.
9. Click the **Reason for Exemption** dropdown menu and select a **reason**.
10. In the *Exemption Context* field, enter an **explanation** for why your app cannot use an install button. It's recommended to provide as many details as possible to ensure the best chance of your request being approved.
11. Enter any questions or additional details you want to provide.
12. If you want to receive communications from HubSpot about products and services, select the **I agree to receive other communications** checkbox.
13. Select the **checkbox** to consent to your personal data being processed. This is a requirement for submitting an exemption request.
14. Submit the form.