Configure OAuth for HubSpot ingestion

The managed HubSpot connector in Lakeflow Connect uses OAuth 2.0 user-to-machine (U2M) authentication. Use the authentication details that you retrieve from the steps on this page to create a Unity Catalog connection in Azure Databricks.

Note

HubSpot retired the legacy public app creation UI. Create your app using HubSpot's project-based platform and the HubSpot CLI, as described on this page. See the HubSpot changelog for details.

Install and authenticate the HubSpot CLI

  1. Install Node.js version 20 or above.

  2. Install the HubSpot CLI:

    npm install -g @hubspot/cli

  3. Authenticate the CLI with your HubSpot account:

    hs account auth

    Follow the prompts to generate a personal access key and save it to your local CLI configuration.

Create an app and retrieve authentication details

  1. Create an app on HubSpot's project-based platform:

    hs project create --project-base app --auth oauth --distribution private

  2. In the generated app-hsmeta.json file, set auth.redirectUrls to your workspace's redirect URL (format: https://<your_workspace_domain>/login/oauth/lakehousefederation.html). For example: https://my-workspace.cloud.databricks.com/login/oauth/lakehousefederation.html

  3. In the same file, set auth.requiredScopes to only the following scopes. Omitting any of these, or adding scopes not listed on this page, causes failures later in the setup process.

    • oauth
    • communication_preferences.read
    • content
    • crm.objects.marketing_events.read
    • crm.objects.marketing_events.write
    • forms
    • forms-uploaded-files
    • marketing.campaigns.read

    Important

    HubSpot CRM Hub object ingestion is in Beta. Workspace admins can control access to this feature from the Previews page by opting into the hubspot_connector_crm_objects preview. See Manage Azure Databricks previews.

    If you've enabled this preview, also add the following scopes to auth.requiredScopes:

    • crm.objects.companies.read
    • crm.objects.contacts.read
    • crm.objects.deals.read
    • crm.objects.leads.read
    • crm.objects.line_items.read
    • crm.objects.orders.read
    • crm.objects.owners.read
    • crm.objects.products.read
    • crm.objects.tickets.read
    • crm.schemas.companies.read
    • crm.schemas.contacts.read
    • crm.schemas.deals.read
    • crm.schemas.line_items.read
    • crm.schemas.orders.read
    • sales-email-read

  4. Deploy the app to your HubSpot account:

    hs project upload

  5. Retrieve the app's authentication details:

    hs project open

    Under Project Components, select your app, then click the Auth tab. Note the Client ID and the Client secret. Use these to create a Unity Catalog connection in Azure Databricks.

  6. Install the app in your HubSpot account:

    1. Go to Development > Projects.
    2. Select your project, then select your app.
    3. On the Distribution tab, click Install now and authorize the app.

Migrate a legacy app

If you already have a legacy public app configured for HubSpot ingestion, migrate it to the project-based platform instead of creating a new app. Migration preserves your app's existing Client ID, Client secret, and installs, so you don't need to update your Unity Catalog connection.

  1. Update the HubSpot CLI to version 7.6.0 or later:

    npm install -g @hubspot/cli@latest

  2. Run the migration command and follow the prompts to select your app and confirm the components to migrate:

    hs app migrate

For details, see HubSpot's migration guide.

Extending an existing HubSpot pipeline with CRM objects

If you already have an existing HubSpot pipeline set up without the CRM objects and want to extend the same pipeline to include them, use the following instructions:

  1. Opt your workspace into the Hubspot Connector CRM Hub Objects preview. See Manage Azure Databricks previews.

  2. On your HubSpot app, add the CRM object scopes to auth.requiredScopes in app-hsmeta.json. For the list of CRM object scopes, see Create an app and retrieve authentication details.

  3. Redeploy the app to your HubSpot account:

    hs project upload

  4. Re-authorize the existing Unity Catalog connection: On your Databricks UI, go to your HubSpot UC connection associated with the pipeline, click Edit, and follow the steps to sign in with HubSpot again so it picks up the added scopes. See Create a HubSpot connection.

You can now edit the pipeline to include the CRM objects. See Ingest data from HubSpot.

Next steps

Use Catalog Explorer to create a connection. Any user with USE CONNECTION or ALL PRIVILEGES can then create pipelines from it. See Create a HubSpot connection.

  • Last updated on