Hubspot auth provider

The Hubspot auth provider enables tools and agents to call Hubspot APIs on behalf of a user. Behind the scenes, the Arcade Engine and the Hubspot auth provider seamlessly manage Hubspot OAuth 2.0 authorization for your users.

What’s documented here

This page describes how to use and configure Hubspot auth with Arcade.

This auth provider is used by:

• The Arcade Hubspot toolkit, which provides pre-built tools for interacting with Hubspot
• Your app code that needs to call Hubspot APIs
• Or, your custom tools that need to call Hubspot APIs

Use Arcade’s Default Hubspot Auth Provider

Arcade offers a default Hubspot auth provider that you can use in the Arcade Cloud. In this case, your users will see Arcade as the name of the application that’s requesting permission.

If you choose to use Arcade’s Hubspot auth, you don’t need to configure anything. Follow the Hubspot toolkit examples to get started calling Hubspot tools.

Use Your Own Hubspot App Credentials

In a production environment, you will most likely want to use your own Hubspot app credentials. This way, your users will see your application’s name requesting permission.

You can use your own Hubspot credentials in both the Arcade Cloud and in a self-hosted Arcade Engine instance.

Before showing how to configure your Hubspot app credentials, let’s go through the steps to create a Hubspot app.

Create a Hubspot App

Hubspot has two types of apps: Public and Private. You will need to create a Public one.

Follow Hubspot’s tutorial to create your Public App. You will need a developer account to do this.

When creating your app, use the following settings:

• Under App Info, choose a name, description, and logo for your app
• Under Auth, enter the Redirect URL: https://cloud.arcade.dev/api/v1/oauth/callback
• In the Scopes section, click Add Scope and add the following scopes with the Conditionally Required scope type:
  • crm.objects.companies.read
  • crm.objects.contacts.read
  • crm.objects.contacts.write
  • crm.objects.deals.read
  • sales-email-read

Create the app and take note of the Client ID and Client Secret. You don’t need to follow Hubspot’s instructions to install the app.

Configuring your own Hubspot Auth Provider in Arcade

There are two ways to configure your Hubspot app credentials in Arcade:

1. From the Arcade Dashboard GUI
2. By editing the engine.yaml file directly (only possible with a self-hosted Arcade Engine)

We show both options step-by-step below.

export HUBSPOT_CLIENT_ID="<your client ID>"
export HUBSPOT_CLIENT_SECRET="<your client secret>"

HUBSPOT_CLIENT_ID="<your client ID>"
HUBSPOT_CLIENT_SECRET="<your client secret>"

auth:
  providers:
    - id: hubspot
      description: "Custom Hubspot provider"
      enabled: true
      type: oauth2
      provider_id: hubspot
      client_id: ${env:HUBSPOT_CLIENT_ID}
      client_secret: ${env:HUBSPOT_CLIENT_SECRET}

Using the Arcade Hubspot Toolkit

The Arcade Hubspot toolkit provides tools to interact with various Hubspot objects, such as companies, contacts, deals, and email messages.

Refer to the toolkit documentation and examples to learn how to use the toolkit to build agents and AI apps that interact with Hubspot services.

Using Hubspot auth in app code

Use the Hubspot auth provider in your own agents and AI apps to get a user-scoped token for the Hubspot API. See authorizing agents with Arcade to understand how this works.

Use client.auth.start() to get a user token for the Hubspot API:

from arcadepy import Arcade
 
client = Arcade(base_url="https://api.arcade.dev")  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "[email protected]"
 
# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="hubspot",
    scopes=["oauth", "crm.objects.companies.read"],
)
 
if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)
 
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
 
token = auth_response.context.token
# Do something interesting with the token...

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade({ baseURL: "https://api.arcade.dev" }); // Automatically finds the `ARCADE_API_KEY` env variable
 
const userId = "[email protected]";
 
// Start the authorization process
const authResponse = await client.auth.start(userId, "hubspot", {
  scopes: ["oauth", "crm.objects.companies.read"],
});
 
if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}
 
// Wait for the authorization to complete
const response = await client.auth.waitForCompletion(authResponse);
 
const token = response.context.token;
// Do something interesting with the token...

You can use the auth token to call Hubspot Companies endpoints and read information about companies. By changing or adding scopes to the client.auth.start call, you can call other Hubspot endpoints.

The scopes supported by the Arcade Hubspot auth provider are the ones listed above. If you created your own Hubspot app, make sure to add the scopes you intend to use in the client.auth.start call.

Using Hubspot auth in custom tools

The Arcade Model API is a convenient way to call language models and automatically invoke tools. You can author your own custom tools that interact with the Hubspot API.

Use the Hubspot() auth class to specify that a tool requires authorization with Hubspot. The authentication token needed to call the Hubspot API is available in the tool context through the context.get_auth_token_or_empty() method.

from typing import Annotated
 
import httpx
 
from arcade.sdk import ToolContext, tool
from arcade.sdk.auth import Hubspot
 
 
@tool(
    requires_auth=Hubspot(
        scopes=["oauth", "crm.objects.companies.read"],
    )
)
async def get_company_details(
    context: ToolContext,
    company_id: Annotated[
        str,
        "The ID of the company to get the details of.",
    ],
) -> Annotated[dict, "Details of the company"]:
    """Gets the details of a company."""
    url = f"https://api.hubapi.com/crm//v3/objects/companies/{company_id}"
    headers = {"Authorization": f"Bearer {context.get_auth_token_or_empty()}"}
 
    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return response.json()

If you are self-hosting Arcade, you will need to restart the Arcade Worker and the Engine for the new tool to be available.

Your new tool can be called like demonstrated below:

from arcadepy import Arcade
 
client = Arcade(base_url="https://api.arcade.dev")  # Automatically finds the `ARCADE_API_KEY` env variable
 
USER_ID = "[email protected]"
TOOL_NAME = "Hubspot.GetCompanyDetails"
 
auth_response = client.tools.authorize(tool_name=TOOL_NAME, user_id=USER_ID)
 
if auth_response.status != "completed":
    print(f"Click this link to authorize: {auth_response.url}")
 
# Wait for the authorization to complete
client.auth.wait_for_completion(auth_response)
 
tool_input = {
    "company_id": "32134490789",
}
 
response = client.tools.execute(
    tool_name=TOOL_NAME,
    input=tool_input,
    user_id=USER_ID,
)
print(response.output.value)

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade({ baseURL: "https://api.arcade.dev" }); // Automatically finds the `ARCADE_API_KEY` env variable
 
const USER_ID = "[email protected]";
const TOOL_NAME = "Hubspot.GetCompanyDetails";
 
// Start the authorization process
const authResponse = await client.tools.authorize({
  tool_name: TOOL_NAME,
  user_id: USER_ID,
});
 
if (authResponse.status !== "completed") {
  console.log(`Click this link to authorize: ${authResponse.url}`);
}
 
// Wait for the authorization to complete
await client.auth.waitForCompletion(authResponse);
 
const toolInput = {
  company_id: "1234567890",
};
 
const response = await client.tools.execute({
  tool_name: TOOL_NAME,
  input: toolInput,
  user_id: USER_ID,
});
 
console.log(response.output.value);