Hubspot
The Hubspot enables tools and to call Hubspot APIs on behalf of a .
Want to quickly get started with Hubspot services in your or AI app? The pre-built Arcade Hubspot MCP Server is what you want!
What’s documented here
This page describes how to use and configure Hubspot auth with Arcade.
This is used by:
- The Arcade Hubspot MCP Server, which provides pre-built 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 that you can use in the Arcade Cloud Platform. In this case, your 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 .
Use Your Own Hubspot App Credentials
When using your own app credentials, make sure you configure your to use a custom user verifier. Without this, your end-users will not be able to use your app or in production.
In a production environment, you will most likely want to use your own Hubspot app credentials. This way, your 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.
If you are implementing your own Hubspot custom
tools, make sure to also add any extra
scopes
necessary for the actions your need to perform. All extra scopes must be
added to the app as Conditionally Required
or Optional
, never as
Required
, otherwise the Arcade Hubspot Server will not work. Read more
about Hubspot scope
types .
Configuring your own Hubspot Auth Provider in Arcade
Dashboard GUI
Configure Hubspot Auth Using the Arcade Dashboard GUI
Access the Arcade Dashboard
To access the Arcade Cloud dashboard, go to api.arcade.dev/dashboard . If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard . Adjust the host and port number to match your environment.
Navigate to the OAuth Providers page
- Under the OAuth section of the Arcade Dashboard left-side menu, click Providers.
- Click Add OAuth Provider in the top right corner.
- Select the Included Providers tab at the top.
- In the Provider dropdown, select Hubspot.
Enter the provider details
- Enter
hubspot
as the ID for your provider - Optionally enter a Description.
- Enter the Client ID and Client Secret from your Hubspot app.
- Note the Redirect URL generated by Arcade. This must be set as your Hubspot app’s Redirect URL.
Create the provider
Hit the Create button and the provider will be ready to be used.
When you use tools that require Hubspot auth using your Arcade credentials, Arcade will automatically use this Hubspot OAuth provider. If you have multiple Hubspot providers, see using multiple auth providers of the same type for more information.
Using the Arcade Hubspot MCP Servers
The Arcade Hubspot MCP Server provides 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 Server to build and AI apps that interact with Hubspot services.
Using Hubspot auth in app code
Use the Hubspot in your own and AI apps to get a -scoped token for the Hubspot API. See authorizing agents with Arcade to understand how this works.
Use client.auth.start()
to get a token for the Hubspot API:
Python
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...
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 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 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
Python
If you are self-hosting, change the base_url
parameter in the Arcade
constructor to match your http://localhost:9099
.
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)