import { Tabs, Callout, Steps } from "nextra/components";

# Hubspot

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

<Callout>
  Want to quickly get started with Hubspot services in your agent or AI app? The
  pre-built [Arcade Hubspot MCP Server](/resources/integrations/sales/hubspot) is what you
  want!
</Callout>

## 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](/resources/integrations/sales/hubspot), which provides pre-built tools for interacting with Hubspot
- Your [app code](#using-hubspot-auth-in-app-code) that needs to call Hubspot APIs
- Or, your [custom tools](#using-hubspot-auth-in-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](/resources/integrations/sales/hubspot) to get started calling Hubspot tools.

## Use Your Own Hubspot App Credentials

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

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](https://developers.hubspot.com/docs/guides/apps/public-apps/overview) to create your Public App. You will need a [developer account](https://app.hubspot.com/signup-hubspot/developers) 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.

<Callout type="info">
  If you are implementing your own [Hubspot custom
  tools](#using-hubspot-auth-in-custom-tools), make sure to also add [any extra
  scopes](https://developers.hubspot.com/docs/guides/apps/authentication/scopes)
  necessary for the actions your tools need to perform. All extra scopes must be
  added to the app as `Conditionally Required` or `Optional`, never as
  `Required`, otherwise the Arcade Hubspot MCP Server will not work. Read more
  about [Hubspot scope
  types](https://developers.hubspot.com/changelog/advanced-auth-and-scope-settings-for-public-apps).
</Callout>

## Configuring your own Hubspot Auth Provider in Arcade


<Tabs items={["Dashboard GUI"]}>
<Tabs.Tab>

### Configure Hubspot Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://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 **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- 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.

</Steps>

When you use tools that require Hubspot auth using your Arcade account credentials, Arcade will automatically use this Hubspot OAuth provider. If you have multiple Hubspot providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

</Tabs.Tab>
</Tabs>

## Using the Arcade Hubspot MCP Servers

The [Arcade Hubspot MCP Server](/resources/integrations/sales/hubspot) provides tools to interact with various Hubspot objects, such as companies, contacts, deals, and email messages.

Refer to the [MCP Server documentation and examples](/resources/integrations/sales/hubspot) 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](/get-started/about-arcade) to understand how this works.

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

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {21}
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...
```

</Tabs.Tab>

<Tabs.Tab>


```javascript {20}
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...
```

</Tabs.Tab>
</Tabs>

You can use the auth token to call [Hubspot Companies endpoints](https://developers.hubspot.com/docs/guides/api/crm/objects/companies) 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](#create-a-hubspot-app). 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](/guides/create-tools/tool-basics/build-mcp-server) 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.

```python {10,23}
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:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>
<Callout type="info">
  If you are self-hosting, change the `base_url` parameter in the `Arcade` constructor to match your Arcade Engine URL. By default, the Engine will be available at `http://localhost:9099`.
</Callout>

```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}"
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)
```

</Tabs.Tab>
<Tabs.Tab>
<Callout type="info">
  If you are self-hosting, change the `baseURL` parameter in the `Arcade` constructor to match your Arcade Engine URL. By default, the Engine will be available at `http://localhost:9099`.
</Callout>

```javascript
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);
```

</Tabs.Tab>
</Tabs>