Skip to main content
After April 5, 2026, all apps listed on the HubSpot Marketplace that wish to make changes to the app listing will be required to use an updated installation flow that includes an option to authenticate using OAuth without a separate partner sign in. You can choose to opt your app into this updated flow early, but once you do so, that app will be required to use the updated flow moving forward. In the updated flow, 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 April 5, 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.
Screenshot of the App Listing page. The "More" dropdown menu that appears upon hover is highlighted, as is the "Edit draft" option.
  1. In the Listing info section, click Enable seamless install flow.
Screenshot of the Listing info tab of the listing editor. The "Enable seamless install" button is highlighted.
  1. 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.
  2. In the Listing info section of the listing editor, click the Install button URL dropdown menu and select a URL.
  3. In the Sign-in configuration section, select whether the app will include partner sign in.
Screenshot of the "Sign-in configuration" section of the "Listing Info" tab.

​
Understand the install flow without partner sign in

​
Developer perspective

1

Receive installation request

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.
2

Complete installation

Once you receive the request, you should:
  • Get the code and returnUrl from the URL parameters.
// Helper function 
function getQueryParam(param) {
    const params = new URLSearchParams(window.location.search);
    return params.get(param);
}

const code = getQueryParam('code');
const returnUrl = getQueryParam('returnUrl');
3

Redirect back to HubSpot

Redirect the user back to the returnUrl provided in the installation request. Redirecting back to HubSpot is required to avoid an infinite login loop.

​
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.
Screenshot of the dialog box where the customer can click Connect app
  1. 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.
    • Click the X in the top right to return to the app listing page.
Screenshot of the dialog box where the app has been installed

​
Understand the install flow with partner sign in

​
Developer perspective

1

Receive initial installation request

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
2

Authorize user

  • Get the step and returnUrl from the URL parameters, then show a login form or page to authenticate the user.
// Helper function 
function getQueryParam(param) {
    const params = new URLSearchParams(window.location.search);
    return params.get(param);
}
const step = getQueryParam('step');
const returnUrl = getQueryParam('returnUrl');
3

Generate security token

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:
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();
4

Save the `state` token and associate it with the user

  • 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.
5

Redirect back to HubSpot

  • Add the state token you generated in the previous step to the returnUrl as a query parameter, 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:
const returnUrlObj = new URL(returnUrl);
returnUrlObj.searchParams.set('state', state);
// 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"
6

Receive final installation request

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
7

Get parameters from the URL

  • Get the step, code, state, and returnUrl parameters from the URL.
// 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');
8

Retrieve the user account associated with the `state` token

  • Validate that the state token matches the original authentication request.
  • Retrieve the associated user account.
9

Finish the process

  • If you are able to verify the state token, complete the installation:
    • Exchange the code for OAuth access and refresh tokens.
    • 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.

​
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. Screenshot of the dialog box where the customer can click Sign in
  5. In the new window, finish the app’s sign up / log in process externally.
Screenshot of the new window where a customer is prompted to sign in to the sample app
  1. After being redirected back to HubSpot, review the app’s requirements, then select the checkbox and click Connect app.
Screenshot of the dialog box where the customer can click Connect app
  1. 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.
    • Click the X in the top right to return the app listing page.
Screenshot of the dialog box where the app has been installed

​
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.
  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.
Screenshot of the Request removal button in the listing editor.
  1. In the exemption request form, enter your name, email address, and company name, then click Next.
  2. Enter your Production app ID.
  3. 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.
  4. Enter your App Name, then click Next.
  5. Click the Reason for Exemption dropdown menu and select a reason.
  6. 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.
  7. Enter any questions or additional details you want to provide.
  8. If you want to receive communications from HubSpot about products and services, select the I agree to receive other communications checkbox.
  9. Select the checkbox to consent to your personal data being processed. This is a requirement for submitting an exemption request.
  10. Submit the form.
Last modified on March 13, 2026