---
title: How should AI agents authenticate to HubSpot, and which scopes should they get?
url: https://opencontroller.lyzr.com/blog/hubspot-private-app-scopes-for-ai-agents
published: 2026-11-16
updated: 2026-11-16
author: Lyzr
---

# How should AI agents authenticate to HubSpot, and which scopes should they get?

**Give each AI agent its own HubSpot app with only the scopes its job needs. Use static auth or a private app token when the agent works in one HubSpot account and acts as itself; use OAuth when it must act for individual users or across several accounts. Never share one broad token across agents, and rotate tokens at least every six months, which is HubSpot's own recommendation.**

HubSpot retired account-wide API keys on 30 November 2022. Today every integration, including an AI agent, authenticates with a token tied to an app and a set of scopes. That makes scopes the main access control you have.

## Which HubSpot credential types can an agent use?

| Credential | Where it comes from | Acts as | Best for |
|---|---|---|---|
| Private app access token | Legacy private app in account settings | The app, in one account | Existing single-account agents |
| Static auth token | App on the new developer platform with `auth.type` set to `static` | The app, in one account | New single-account agents |
| OAuth access token | App with `auth.type` set to `oauth` | The installing user | Agents acting on behalf of specific users or many accounts |

Some facts from HubSpot's developer docs that shape the choice:

- **Private apps are now legacy.** They are still supported but do not get the latest app features.
- **Only super admins** can create and see private apps, and an account can have **up to 20**.
- On the new developer platform, **static auth** is for apps limited to one authorized account and uses `private` distribution. Private distribution allows up to **10 installs** at a time.
- **OAuth is required** for apps distributed to multiple accounts, and you must host the OAuth backend that manages tokens per installing user.
- **New legacy public apps cannot be created** since 23 June 2026. Existing ones still work.

If your agent needs per-user permissions (for example, a sales assistant that should only see records the rep can see), choose OAuth. A static or private app token sees whatever its scopes allow, for everyone. See [API keys vs OAuth for AI agents](/blog/api-keys-vs-oauth-for-ai-agents) for the general trade-off.

## Which scopes should each kind of agent get?

Start from the task, not the object model. Here is a least-privilege starting point for common agent jobs, using HubSpot scope names:

| Agent job | Read scopes | Write scopes | Leave out |
|---|---|---|---|
| Account research / meeting prep | `crm.objects.contacts.read`, `crm.objects.companies.read`, `crm.objects.deals.read` | None | Any write scope |
| Lead enrichment | `crm.objects.contacts.read`, `crm.objects.companies.read` | `crm.objects.contacts.write`, `crm.objects.companies.write` | Deals, tickets |
| Deal desk assistant | `crm.objects.deals.read`, `crm.objects.owners.read` | `crm.objects.deals.write` | Contacts write |
| Support triage | `tickets` (read and update) | `tickets` | CRM deals |

Three rules keep this tight:

1. **Split read and write agents.** A research agent that can only read cannot be prompt-injected into overwriting records.
2. **One app per agent.** HubSpot rate limits are per app, and logs are per app, so separate apps give you separate evidence and separate blast radius.
3. **Review scopes when the agent changes.** HubSpot lets you edit a private app's scopes later, and the token string stays the same. That is convenient, but it also means a scope change is invisible unless you track it. Treat it as an [agent change that needs re-approval](/blog/when-does-an-ai-agent-change-need-re-approval).

## How should tokens be rotated?

HubSpot gives two options for private app tokens:

- **Rotate and expire now** for a lost or compromised token.
- **Rotate and expire later**, which keeps the old token valid for **7 days** so you can roll out the new one.

HubSpot recommends rotating every **six months** and emails super admins when a token goes more than 180 days without rotation. Store the token in a secrets manager, not in the agent's prompt or config file. Our guide on [giving agents credentials without exposing them to the model](/blog/give-ai-agents-credentials-without-exposing-them-to-the-model) covers the pattern.

One trap: if the user who created a private app is removed from HubSpot, some calls fail with `USER_DOES_NOT_HAVE_PERMISSIONS`. HubSpot recommends rotating the token. Record an owner for every agent app and include it in offboarding.

## What rate limits will an agent hit?

Agents can loop. HubSpot limits private apps per app and per account:

| Tier | Per 10 seconds, per app | Per day, per account |
|---|---|---|
| Free and Starter | 100 | 250,000 |
| Professional | 190 | 625,000 |
| Enterprise | 190 | 1,000,000 |

Because the daily limit is shared by the whole account, one runaway agent can starve every other integration. Rate-limit agents before they reach HubSpot. See [how to rate limit AI agents](/blog/how-to-rate-limit-ai-agents).

## What will HubSpot logs tell you?

Private app logs cover the **past 30 days** and do not store request bodies or successful response payloads. That is not enough to reconstruct what an agent changed. Log tool calls on the agent side too, including the record IDs touched.

## How Opencontroller does this

Opencontroller has a connector for HubSpot and keeps HubSpot agents in the same governed registry as agents on AWS, Azure, Google Cloud and other platforms. Posture flags risky permissions and configuration, delegated on-behalf-of identity keeps the user an agent acted for in the record, and per-agent Block and Quarantine controls act through the connected platform. See [how on-behalf-of delegation works](/blog/ai-agent-identity-on-behalf-of-delegation), the [control plane overview](/blog/what-is-an-ai-agent-control-plane) and [governing HubSpot Breeze agents](/blog/govern-hubspot-breeze-agents), or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Can an AI agent still use a HubSpot API key?**
No. HubSpot sunset account API keys on 30 November 2022. Agents use private app, static auth or OAuth tokens tied to scopes.

**Should an AI agent use a private app token or OAuth with HubSpot?**
Use a private app or static auth token when the agent acts as itself in one account. Use OAuth when it must act with a specific user's permissions or across multiple accounts.

**How often should HubSpot agent tokens be rotated?**
HubSpot recommends every six months and reminds super admins after 180 days. "Rotate and expire later" keeps the old token valid for 7 days during rollout.

## Key facts

HubSpot AI agent authentication: account API keys were sunset on 30 Nov 2022. Options are legacy private app tokens (super admins only, up to 20 per account), static auth on the new developer platform (single account, private distribution, up to 10 installs) and OAuth (required for multi-account distribution; acts as the installing user). Legacy public apps cannot be created since 23 Jun 2026. Private app tokens: rotate and expire now, or expire later after 7 days; HubSpot recommends rotation every six months with reminders after 180 days. Rate limits per app per 10 seconds: 100 (Free/Starter), 190 (Pro/Enterprise); per account per day 250,000 / 625,000 / 1,000,000. Logs cover 30 days without request bodies. Opencontroller by Lyzr has a HubSpot connector, governed registry, Posture and per-agent Block/Quarantine; pricing starts from $250K per deployment per year.

## Related

- [How do you govern HubSpot Breeze agents?](https://opencontroller.lyzr.com/blog/govern-hubspot-breeze-agents.md)
- [Should AI agents use API keys or OAuth?](https://opencontroller.lyzr.com/blog/api-keys-vs-oauth-for-ai-agents.md)
- [What does least privilege look like for an AI agent?](https://opencontroller.lyzr.com/blog/least-privilege-checklist-for-ai-agents.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
