Connect HubSpot
Create a private app with six read scopes, paste the token, and what the first collect reads.
One private app, six read scopes, one token. Two minutes.
Create a private app
- In HubSpot, open Settings → Integrations → Private Apps and create an app. Name it after this product so its purpose is obvious in a year.
- On the Scopes tab, tick exactly these six. They are all read scopes.
| Scope | What it lets the collector read |
|---|---|
| automation | workflows: definitions, enrollment criteria, actions |
| forms | forms and the properties they write |
| crm.lists.read | lists and their filters |
| crm.schemas.contacts.read | contact property definitions and groups |
| crm.schemas.companies.read | company property definitions and groups |
| crm.schemas.deals.read | deal property definitions, pipelines and stages |
- Create the app and copy the token. HubSpot shows it once.
Do not widen an app you already have. A token scoped to one job is a blast-radius property worth keeping, and a separate read-only app is always the right shape.
Paste the token
In your workspace, the first card is Connect HubSpot. Paste the token and confirm. The token is written to the workspace's env file and never shown again; the config names where the token lives, never its value. To replace it later, use Settings → Connections → Rotate.
What the first collect reads
Every workflow: its trigger, enrollment criteria, branches, and every field it reads, writes, branches on or re-enrolls on, including writes that land on an associated record. Every form and the properties it writes. Every list and its filters. Then the stages collector reads the ordered values of your pipeline and lifecycle fields, and where each property is filed. A portal with a few hundred workflows takes about two minutes.
Reads workflow, form, list and property definitions. Never contact, company or deal records.
Afterwards
The connection's pill on the overview reads complete when both automations and edges were fully collected. Edges partial after a first collect is normal on a portal with association-scoped writes whose type the API does not name; those edges are listed as gaps rather than guessed. Broken with a 401 means the token was revoked or a scope is missing, and the error names which. Troubleshooting has the rest.