Build agents
Actions Gallery
Authentication
Hubspot

Authenticate with HubSpot API

This guide provides an overview of two methods for authenticating with the HubSpot API:

  1. Use OAuth2 with public apps (temporary access token) - preferred
  2. Generate a long-lived access token with private apps

Choose one method (the first one is recommended) and follow the steps below to set up your HubSpot action package authorization effectively.

Set up HubSpot OAuth2 client

OAuth2 is the industry-standard protocol for authorization. By using OAuth2 with public apps, you can securely authorize your app (client) to access HubSpot data via API.

Use the OAuth2Secret type of secret within your actions. This ensures the flow initializes from the UI to set up API access.

Create an app

  • Navigate to your HubSpot developer account and create a new public app.
  • Fill in basic information like app name, logo, and description.
  • Go to the Auth tab to set up the redirect URI and scopes.

Create a public app

Set redirect URLs

Add a URL matching what is expected in Studio: http://localhost:4567 (note that it's http and not https).

Set up redirect URLs

Configure scopes

  • Turn on advanced scope settings. HubSpot will enable this later if not configured initially.
  • Required scopes for the action package include:
    • crm.objects.companies|contacts|custom|deals.read
    • tickets

Check the OAuth2Secret type annotations from your package to ensure all required scopes are captured.

Scopes settings

Test app initialization

  • Save settings and copy the "Sample install URL (OAuth)" like: https://app-eu1.hubspot.com/oauth/authorize?client_id=05ffd287-41db-4def-8e4d-8fa4ed23bb76&redirect_uri=http://localhost:4567&scope=oauth.
  • Paste this URL in your browser to install the app in a test account. You should see the flow redirecting to the localhost address with a code.

To install the app in your production HubSpot account, the public app must be published, reviewed, and approved by HubSpot, or installed by a user with App Marketplace Access permission.

Client credentials

Set up app credentials in Sema4.ai Studio

  • Retrieve your app's client ID and secret from the Auth tab.
  • Set these in Studio under Settings -> Permissions -> HubSpot.

client credentials

Acquire an access token

If you cannot use the OAuth2 flow, you need to supply a mandatory secret called the access token. This long-lived token never expires and should be kept safe and rotated if leaked. It is tied to a "Private App" that you need to create.

Use the Secret type of secret within your actions to complete this static secret during AI Agent deployment in the Sema4.ai Studio UI.

Select account for access

Go to HubSpot (opens in a new tab) and select the account you want to give the actions access to.

Create a private app

Click the cog wheel button on the top-right side of the menu bar to enter the Settings menu.

settings cog

From the left pane, go to Integrations > Private Apps and create an app.

Add required scopes

Ensure you add the required scopes. These represent the permissions you give to the actions over the resources. Required permissions include:

  • crm.objects.companies|contacts|custom|deals.read
  • tickets

Check the OAuth2Secret type annotations from your package to ensure all required scopes are captured.

app scopes config

Get the generated access token

With the app created and scopes set, retrieve the generated access token and use it in the UI during agent deployment.

app auth access token

GoogleMicrosoft