> ## 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 select one of several install experiences - authenticating using [OAuth](/docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) with or without partner sign in, logging in directly through a partner site, or not featuring an install button at all.
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:
* All apps listed on the HubSpot Marketplace that make changes in the listing editor.
* 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 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 using a new install experience early
You can choose to switch to one of the new install experiences any time before October 26, 2026. After this date, it will be required in all accounts to select an install experience when you next edit an app's listing.
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 Install Experience**.
4. In the dialog box, select the **checkbox** that shows you understand you can't return to the previous install flow, then click **Enable Install Experience**.
5. In the app listing editor, select an **option** in the *Install experience* section:
* **Seamless install:** installs in HubSpot with a guided OAuth flow. Best for apps that want a native install flow in HubSpot.
* **Login via partner site:** sends customers to an external sign-up or install flow. Best for apps that require additional setup.
* **No install button:** no install button appears on the app listing. Best for apps that can’t yet support an install flow. Users will be shown a contact us or demo request button.
6. If you're using the *Seamless install* experience:
* Click the **Install Button URL** dropdown menu and select a **URL**. These URLs are populated from the redirect URLs set in your [app settings](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#manage-authentication).
* In the *Sign-in configuration* section, select whether the app will require a separate partner sign-in.
7. If you're using the *Login via partner site* experience, enter an **install button URL** that leads to the page on your partner site where the customer can install the app.
## Understand the Seamless install flow without partner sign in
### Use the Seamless install flow
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 app listing editor, select **Seamless install** in the *Install experience* section:
4. Click the **Install Button URL** dropdown menu and select a **URL**. These URLs are populated from the redirect URLs set in your [app settings](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#manage-authentication).
5. In the *Sign-in configuration* section, select **No partner login required, HubSpot OAuth only**.
### 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](/docs/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 Seamless install flow with partner sign in
### Use the Seamless install flow
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 app listing editor, select **Seamless install** in the *Install experience* section:
4. Click the **Install Button URL** dropdown menu and select a **URL**. These URLs are populated from the redirect URLs set in your [app settings](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#manage-authentication).
5. In the *Sign-in configuration* section, select **Include 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](/docs/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.
## Understand the Login via partner site install flow
### Developer perspective
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 app listing editor, select the **Login via partner site** option in the *Install experience* section.
4. In the *Install button URL* field, enter the **URL** of the external page where customers can install your app. This link should not direct to your homepage or your setup documentation.
### 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 new window that opens, install the app from the developer's website.
5. When the installation is complete, return to HubSpot.
## Understand the No install button flow
### Developer perspective
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 app listing editor, select the **No install button** option in the *Install experience* section.
4. To add a meetings link, click the **Add meetings URL** dropdown menu and select a **scheduling page**. To create a new scheduling page, click **Create meetings link**. Learn more about working with [scheduling pages](https://knowledge.hubspot.com/meetings-tool/create-and-edit-scheduling-pages).
5. To add a form, click the **Add contact form** dropdown menu and select a **form**. To create a new form, click **Create contact form**. Learn more about [working with contact forms](https://knowledge.hubspot.com/forms/create-and-edit-forms).
### 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 right, click **Schedule demo**.
4. If multiple options are available, click the **Schedule demo** dropdown menu and select **Schedule meeting** or **Request to be contacted**.
## 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.