Hubspot

The Hubspot auth provider enables tools and agents to call Hubspot APIs on behalf of a user.

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 MCP Server, 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 Platform. 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 MCP Server 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.

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 generated by Arcade (see below)
• 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

Using the Arcade Hubspot MCP Servers

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

Refer to the MCP Server documentation and examples to learn how to use the MCP Server 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 = "{arcade_user_id}"
 
# 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 = "{arcade_user_id}";
 
// 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

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_tdk import ToolContext, tool
from arcade_tdk.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()

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 = "{arcade_user_id}"
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 = "{arcade_user_id}";
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);