**Note** from Bead: Hubspot · [canonical source](https://redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/2026-06-25/notes/00-hubspot-orientation.md) · session 2026-06-25 · discussion: Talk: Hubspot
This note is the captured vantage of the opening session. It tells a denovo agent **what was decided, what to build, and what is blocked** so it can keep working without conversational carryover.
## Why this bead exists Stephen invoked `start-bead hubspot` and `research hubspot api and token/key access`. HubSpot is one of the clouds the **Simtable content/CRM pipeline** must read from (and the system it is migrating *off* of — see [`bc2bd3b1`](https://redfish.acequia.io/guerin/.agents/bc2bd3b1/), which frames the Acequia-native CRM as *replacing the Zendesk→HubSpot path*). Per the cloud-auth membrane directive, every cloud gets **a follow-along token how-to + a two-legged adapter `.mjs`** — acequia at core, cloud peripheral, auth as the goes-inta/goes-outa membrane. This bead produces that pair for HubSpot.
## The decision (auth method) For a **single HubSpot account, server-side, read/write Contacts** adapter — which is exactly our shape (two-legged backend, not a marketplace app): **→ Use a HubSpot Private App access token.** - Static, non-expiring, per-account token with a fixed scope set. Lives under Settings → Integrations → Private Apps (now also surfaced as Development → Legacy apps; "legacy" means HubSpot is steering people to Service Keys, *not* that private apps are removed — they are fully supported). - Requires a **Super Admin** to create. Available on **all tiers including Free**. - Header: `Authorization: Bearer <token>` (tokens prefixed `pat-...`). Never as a query param. **Do NOT use:** - **API keys (`hapikey`)** — dead since 2022-11-30. They do not work in 2026. - **OAuth 2.0** — only needed for multi-account / marketplace apps; unnecessary token-refresh overhead for our single-account case. **Future migration target:** **Service Keys** (public beta since 2026-02-10) are HubSpot's intended successor to legacy private apps for non-OAuth system-to-system use. Same `Bearer` header. **No webhook support.** Adopt once GA; Private App token is the production-safe choice today. Full detail, endpoints, rate limits, and citations are in [`hubspot-api-and-auth-research.md`](https://redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/2026-06-25/notes/hubspot-api-and-auth-research.md).
## Decisions (resolved by Stephen, 2026-06-25) - **Scope direction: read + write.** Bidirectional sync, not ingest-only. Grant both `.read` and `.write` on all four objects. - **Objects: Contacts, Companies, Deals, Tickets** (all four). Tickets included because we're replacing the Zendesk side. - **Build: both** the token how-to skill and the adapter `.mjs`. → DONE this session: - [`skills/mint-hubspot-token/SKILL.md`](https://redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/2026-06-25/skills/mint-hubspot-token/SKILL.md) — follow-along Super-Admin → Private App mint, with the full read+write scope table for all four objects. - [`artifacts/hubspot-adapter.mjs`](https://redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/2026-06-25/artifacts/hubspot-adapter.mjs) — two-legged Node adapter (Node ≥18 native fetch). Ingest (`export`, paginated) + egress (`upsert`, batch) for all four objects; 429 back-off + rate-limit-header self-throttle; contact→CardDAV vCard mapper; token resolved from `$HUBSPOT_TOKEN` / `--token` / `.credentials/hubspot-*.txt`. Syntax-checked; not yet run (no token). Prefer **paged list + batch read** over the Search API for full export (Search is capped at 4 req/s and returns no rate-limit headers).
## Still blocked (parciante input) - [ ] **Whose HubSpot account?** Which Simtable/Redfish HubSpot account are we integrating — and who is its Super Admin (only a Super Admin can mint the token)? Until this is answered, the adapter has nothing to authenticate against. - [ ] **Credential custody name** — adapter expects `.credentials/hubspot-<account-slug>.txt` (e.g. `hubspot-simtable.txt`), consistent with the host-to-token map. Confirm the slug. - [ ] **Account tier** (not blocking) — sizes a bulk export against the daily cap (Free/Starter 250k/day vs Pro 625k vs Enterprise 1M).
## Pointers - Downstream consumer / why this matters: [`bc2bd3b1`](https://redfish.acequia.io/guerin/.agents/bc2bd3b1/). - Pattern instantiated: cloud-auth goes-inta/goes-outa membrane (per-cloud follow-along token how-to + two-legged adapter). - Primary external source: https://developers.hubspot.com (Private Apps, CRM Contacts v3, usage guidelines).
## For the denovo agent Read order: this note → the research brief. New notes → dated `notes/`. The adapter → `artifacts/`. The token how-to → `skills/`. Chat log → `chats/`, verbatim. Do not write HubSpot secrets into this tree. Do not write into Stephen's global `guerin/notes|skills|chats/`.