> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Let AI Agents Update HubSpot CRM Records

> Let agents work with HubSpot contacts, companies, deals, and tickets. Connect with OAuth, and the gateway injects tokens so agents never see them.

## Overview

Buckle connects AI agents to HubSpot through OAuth. Agents can read and manage CRM records including contacts, companies, deals, and tickets. The gateway injects OAuth credentials into requests to the HubSpot API automatically.

> [!NOTE]
>
> On self-hosted Buckle, HubSpot needs your own HubSpot app first. See [Self-hosted](#self-hosted).

## What you will set up

* A HubSpot connection through OAuth, with read access by default and optional write scopes
* Automatic token injection on HubSpot API requests
* Per-agent, per-tool access to CRM records

## Setup

**1. Open the app**

Open the Buckle dashboard and navigate to **Settings** > **Apps** > **HubSpot**.

**2. Authorize**

Click **Connect HubSpot**. You'll be redirected to HubSpot to authorize Buckle. Review the requested permissions and click **Grant access**.

![Buckle connect window for HubSpot on Cloud, showing the Connect to HubSpot button.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/hubspot/buckle-connect-hubspot.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=1f138af35209859b1c355edbaaf60825)

The HubSpot connect window on Buckle Cloud.

Buckle requests read access to contacts, companies, deals, owners, and tickets by default. Write access and additional scopes (line items, quotes, lists, schemas) are optional.

**3. Verify**

After authorization, you'll be redirected back to the dashboard. The connection will show as **Connected** with your HubSpot portal domain.

## Self-hosted: use your own HubSpot app

> [!NOTE]
>
> **Skip this section on Buckle Cloud.** It's only for self-hosted Buckle without `HUBSPOT_CLIENT_ID` and `HUBSPOT_CLIENT_SECRET` set, or if you want your own company name on HubSpot's consent screen.

> [accordion] 1. Create the HubSpot app
>
> Sign in to a [HubSpot developer account](https://developers.hubspot.com/) (free). Open **Apps** > **Create app**, name it `Buckle`, and open the **Auth** tab.

> [accordion] 2. Add the scopes
>
> Under **Scopes**, add these as **Required**:
>
> `crm.objects.contacts.read`, `crm.objects.companies.read`, `crm.objects.deals.read`, `crm.objects.owners.read`, `tickets`
>
> ![HubSpot app Scopes section with six required scopes: crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read, crm.objects.owners.read, tickets, and oauth.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/hubspot/01-scopes.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=5a9efa7f46167bb5fb0e44ec79b1dd01)
>
> The required scopes in HubSpot. HubSpot adds oauth on its own.
>
> Add these as **Optional**, so agents can get write access when you grant it:
>
> `crm.objects.contacts.write`, `crm.objects.companies.write`, `crm.objects.deals.write`, `crm.objects.line_items.read`, `crm.objects.quotes.read`, `crm.lists.read`, `crm.schemas.contacts.read`, `crm.schemas.companies.read`, `crm.schemas.deals.read`

> [accordion] 3. Add the redirect URL
>
> In Buckle, open **Settings** > **Apps** > **HubSpot** > **Custom credentials** and copy the **Redirect URI**. In HubSpot, paste it into **Redirect URLs** on the **Auth** tab, and save.
>
> ![HubSpot Redirect URLs section with one entry: https://buckle.example.com/v1/apps/hubspot/callback.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/hubspot/02-redirect-url.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=90a3bae1bb76c93d8a46962414af70fe)
>
> The Buckle Redirect URI in HubSpot's Redirect URLs.
>
> ![Buckle Custom credentials card for HubSpot with the setup guide link, the Redirect URI and its copy button, and the client ID and secret fields.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/hubspot/buckle-custom-credentials-hubspot.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=cd00ef03a933acb47b5b234c6cf0d7d8)
>
> Copy the Redirect URI from Custom credentials in Buckle.

> [accordion] 4. Connect with your app
>
> On the **Auth** tab, copy the **Client ID** and **Client secret**. Paste both into **Settings** > **Apps** > **HubSpot** > **Custom credentials**, select **Save credentials**, then **Connect** and grant access in HubSpot.

## What agents can do

| Area | Description |
| - | - |
| **Contacts** | Read, create, and update contact records and properties |
| **Companies** | Read, create, and update company records |
| **Deals** | Read, create, and update deals and pipeline stages |
| **Tickets** | Read, create, and update support tickets |
| **Owners** | View record owners and assignments |
| **Lists** | View contact lists (read-only) |
| **Quotes & Line Items** | View quotes and line item records (read-only) |
| **Schemas** | View property definitions for contacts, companies, and deals |

## Use cases

* CRM enrichment agents that update contact records with data from other sources
* Sales pipeline agents that track deals and update stages
* Support agents that create and triage tickets
* Reporting agents that pull CRM data for analysis

## Controlling access

Access is per agent: [grant](/docs/guides/agent-access.md) the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — a read-only agent is a single grant. Organization [rules](/docs/guides/rules.md) add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches the HubSpot API.

## FAQ

> [accordion] Can I give an agent read-only HubSpot access?
>
> Yes. Buckle requests read access by default, and write scopes are optional. A read-only agent is also a single [grant](/docs/guides/agent-access.md).

> [accordion] Does the agent see my HubSpot token?
>
> No. The token stays in Buckle, and the gateway adds it at the proxy. See [How it works](/docs/how-it-works.md).

> [accordion] How do I reconnect HubSpot?
>
> Open **Settings** > **Apps** > **HubSpot** and connect again. Agents with access use the new connection automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.