**Bead** `1e0ce614-08fc-41e2-8662-7cc56110f9c2` · [canonical URI](https://redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/) · discussion: Talk: Hubspot This page is the wiki facet of a [bead](https://redfish.acequia.io/guerin/.agents/); the bead is the source of truth.
## Identity - **URI:** https://redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/ - **Local origin:** `sites/redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/` - **GUID:** `1e0ce614-08fc-41e2-8662-7cc56110f9c2` - **Created:** 2026-06-25 - **Currently animated by:** Claude (CV — Claude Code, shell + filesystem) - **Invoked by:** Stephen (parciante)
## Motivation (Why a GUID) This bead exists to research and hold the **HubSpot API surface and its token/key access model** so that an Acequia-native adapter can read and (eventually) write HubSpot CRM data. It is a **thread-of-work + reference** bead: the topic (HubSpot integration) does not fit cleanly under any existing bead and deserves its own URI-space because HubSpot is one of the clouds the Simtable content/CRM pipeline must membrane against. It sits downstream of two prior commitments: - **Simtable CRM migration** — bead [`bc2bd3b1`](https://redfish.acequia.io/guerin/.agents/bc2bd3b1/) (simtable-size-up / simtable-pipeline-acequia-crm): the near-term build of an Acequia-native CRM (CardDAV contacts + asset catalogs) **replacing the Zendesk→HubSpot path**. To migrate off HubSpot you must first be able to read HubSpot — this bead supplies that capability. - **Cloud-auth membrane** — the directive that cloud integration is *acequia at core, cloud peripheral*, where auth is the **goes-inta / goes-outa membrane** (ingest read-scope / egress write-scope, gates not Connectors), and **each cloud gets a follow-along token how-to + a two-legged adapter `.mjs`**. This bead produces exactly that pair for HubSpot.
## Mechanism (What this bead does) **Goes here:** - Research notes on HubSpot's auth options (Private App tokens, Service Keys, OAuth, dead API keys), CRM Objects API v3, rate limits, scopes. - A follow-along **token how-to** (the Super-Admin → Settings → Private App path) so a parciante can mint their own scoped HubSpot credential. - A future **two-legged adapter `.mjs`** (read-scope ingest first) when the build phase begins. - The verbatim chat log of the sessions that build this. **Does NOT go here:** - HubSpot secrets/tokens. Tokens live in `.credentials/` (per the host-to-token convention), never in the bead tree. - The Acequia CRM build itself — that is `bc2bd3b1`'s territory. This bead is the *HubSpot-facing membrane*, not the CRM. **Handoff posture:** A denovo agent should be able to read `about.md` + `notes/00-hubspot-orientation.md` and immediately know which auth method to use, what to build, and what is still blocked on the parciante (account access, who owns the HubSpot account).
## Folder Layout ``` 1e0ce614-08fc-41e2-8662-7cc56110f9c2/ ├── about.md # this file ├── uploads/ │ └── README.md # inbound dock └── 2026-06-25/ ├── notes/ │ ├── 00-hubspot-orientation.md # READ FIRST — frame, decision, blockers │ └── hubspot-api-and-auth-research.md # full technical brief (cited) ├── skills/ │ └── mint-hubspot-token/SKILL.md # follow-along token mint (read+write, 4 objects) ├── chats/ │ └── 2026-06-25-hubspot-api-research.md └── artifacts/ └── hubspot-adapter.mjs # two-legged read+write adapter (4 objects) ```
## Session Log - **2026-06-25 (opened, Claude/CV, invoked by Stephen):** Bead opened via `start-bead hubspot`. Seeded with a cited HubSpot API + auth research brief (web research against developers.hubspot.com) and an orientation note. **Decision reached:** for a single-account server-side adapter, use a **Private App access token** (production-safe today; Service Keys are the future migration target once GA). **Stephen scoped it (same session):** read **+ write**, all four objects (**Contacts, Companies, Deals, Tickets**), build **both** deliverables. Built: [`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 token mint) and [`artifacts/hubspot-adapter.mjs`](https://redfish.acequia.io/guerin/.agents/1e0ce614-08fc-41e2-8662-7cc56110f9c2/2026-06-25/artifacts/hubspot-adapter.mjs) (two-legged read+write adapter, syntax-checked, not yet run). Still blocked on parciante: which HubSpot account + who is its Super Admin, and the credential slug — no token obtained yet.
## Modus Operandi (How to interact) - **Reading order:** `about.md` → `notes/00-hubspot-orientation.md` → `notes/hubspot-api-and-auth-research.md`. - **New notes** go in the dated `notes/` folder. **Polished deliverables** (the adapter `.mjs`, a mint-token skill) go in `artifacts/` or `skills/` respectively. - **Chats** go in `chats/`, verbatim, incrementally. - **Cross-bead references** use absolute URIs. - **Do NOT write** HubSpot secrets anywhere in this tree, nor into Stephen's global `guerin/notes|skills|chats/` spaces.
## Capabilities This bead hosts the authoritative-for-us HubSpot API knowledge and can be cited for: which auth method to use, the Contacts API shapes, pagination, rate limits, and the scopes needed. It does NOT produce the Acequia CRM, and it does NOT hold live credentials.
## Lifecycle - **Energization:** charged when the Simtable CRM migration needs to pull from or push to HubSpot, or when a parciante needs to mint a HubSpot token. - **Apoptosis:** fades once the HubSpot membrane (`.mjs` adapter + token how-to) is built, deployed, and folded into `bc2bd3b1`'s pipeline — at which point this bead is a reference, not active work.
## Limitations This bead is NOT the CRM and NOT a credential store. The rate-limit numbers in the research note are point-in-time (June 2026) and add-on-dependent; treat the live `X-HubSpot-RateLimit-*` response headers as ground truth. Auth-method labels ("legacy") track HubSpot's evolving UI; re-verify before a production build if months have passed.
## Related beads - [`bc2bd3b1`](https://redfish.acequia.io/guerin/.agents/bc2bd3b1/) — Simtable size-up / pipeline / Acequia-native CRM (the downstream consumer; HubSpot is the cloud this bead membranes against). - The cloud-auth membrane directive (goes-inta/goes-outa; Slack bead `c915581b` note 01) — the pattern this bead instantiates for HubSpot.
See all: Beads