HubSpot

The engine reads companies, contacts, deals and tickets from your HubSpot account into a knowledge base. HubSpot publishes no API for knowledge-base articles, so articles are not read.

Content is read in place, in your deployment, in your own account. LightHouse receives ids, hashes and counts only. The records are not transmitted, and LightHouse does not open the credential.

The way to connect

Way	What you do
Paste a private app’s access token	Make a private app in HubSpot (Settings → Integrations → Private apps) with the read scopes below, and paste its access token (pat-)

Connect in LightHouse

You need the Client administrator (client_admin) role, signed in as a person, and a deployment whose engine reads this connector (compatibility reference) and keeps credentials in your own store.

1. Go to Setup and admin → Connectors, find HubSpot (search for it, or filter by its family), and choose Connect.
2. Fill in objects (companies, contacts, deals, tickets) and, if you want links back to HubSpot, portal_id.
3. Under What agents may do with it, keep Read only unless your agents are to write through approved cards.
4. Paste the private app’s access token. Your browser seals it to your deployment; LightHouse never sees it.
5. Your deployment keeps it and checks it at the provider. The card shows the result.

Connect in code

- id: hubspot-knowledge
  purpose: Read HubSpot into the knowledge base.
  executor: python
  target: aal_engine.ingest.connector:run_card
  overseer: ops-lead@example.com
  budget_usd: 0
  effect: internal
  source:
    kind: hubspot
    objects: [companies, deals, tickets]
    properties:                       # optional: the properties read, per object
      tickets: [subject, content, hs_pipeline_stage]
    portal_id: 1234567                # optional: links each record to HubSpot
    label: internal
    credential_secret: <connection id>
    requires:
      reads: [hubspot:companies, deals and tickets]
      reason: the service agents answer from the account and ticket history

Scopes

• Read only: crm.objects.companies.read, crm.objects.contacts.read, crm.objects.deals.read and tickets, for the objects you name.
• Read and write: the matching .write scopes, for agents that write through approved cards.
• The health check: HubSpot states a private app’s scopes (its token-information endpoint), and your deployment reports them. Any .write scope on a connection chosen as Read only marks it failing with a warning to narrow the token.
• One host: every call goes to api.hubapi.com.

Where the credential is held

LightHouse never opens this credential. It is sealed in your browser, or by lighthouse-ai connect hubspot --credential-stdin, to your deployment’s own key, and your deployment keeps it in your own secrets store under lighthouse/connectors/hubspot/<connection id>. A request that sends it to LightHouse unsealed is refused with 422 sealing_required. LightHouse keeps the connection’s fingerprint, the access level, the scopes the provider states and when it was checked: never the credential, and never what it reads.

See Where every credential is held.

What is indexed

• Companies, contacts, deals and tickets: the properties named, with sensible ones by default. A contact is read for the business record only: not every property your portal holds about a person.
• How often, and what is read each time: on the card’s schedule. Each pull searches for records whose hs_lastmodifieddate is after the cursor, in order. HubSpot’s search answers at most 10,000 results to one query, so a large first pull starts again from the newest change it has read and carries on.
• Deletions: every six hours the ids are listed and an archived record is removed.
• Rate limits: the search API’s per-second limit is respected by pacing, and a 429 waits as long as HubSpot asks.
• Never read: the knowledge base (HubSpot has no API for it), emails, files and engagements.

Check it worked

• The source’s run note in your deployment: written N, unchanged N, quarantined N, removed N.
• Agents → Knowledge: documents from hubspot.
• Content is read in place, in your deployment. LightHouse receives ids, hashes and counts only; the records are not transmitted.

Removing it

On the card, choose Disconnect. Your deployment deletes the credential from your store. Rotate or delete the token on the private app’s Auth tab in HubSpot. Documents already written stay in the corpus until you delete them.