Skip to main content
If your app authenticates using OAuth, you can choose not to require a separate sign in. The following sections will outline how the app installation process will work with and without a required sign in beyond OAuth.

​
Understand the app install flow without partner sign in

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

Complete installation

Once you receive the request, you should:
  • Use the provided code to finalize app setup on your server.
  • Store any necessary configuration data associated with the user’s HubSpot account.
3

Redirect back to HubSpot

Redirect the user back to the returnUrl provided in the installation request. Without this step, the user will be stuck in an infinite login loop.

​
Understand the app install flow with partner sign in

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

Authorize user

The user completes your system’s login or signup process.
3

Generate security token

Once the user has authenticated, you should:
  • Generate a secure, randomized token unique to this user. This is the state token used in future steps.
  • Save this token in your database.
  • Associate the token with the user’s account. If you are using cookies, tag the cookies with SameSite=none.
4

Redirect back to HubSpot

Add the state token you generated in the previous step to the returnUrl, then redirect the user back to HubSpot. The redirect will look like this: ${returnUrl}?state=${state}.
5

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

Retrieve the user account

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

Finish the process

  • If you are able to verify the state token, complete the installation:
    • Complete installation using the code.
    • Save the resulting api_token.
    • 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.
Last modified on December 10, 2025