IR HubSpot Backend

This is the “brain” for the IR HubSpot integration app. It holds all secrets, validates inbound HubSpot v3 signatures, and makes outbound CRM calls using per-portal OAuth tokens. The HubSpot project (UI cards/settings) talks to these endpoints via hubspot.fetch.

Endpoints

• POST /api/cards/abe-overview?portalId=<id>&objectId=<id> — ABE Overview card data for a company. Returns { ok, isTargetAccount, categories, salesforceUrl }.
• GET|PUT /api/settings?portalId=<id> — settings skeleton (signed).
• GET|POST /api/settings/instantly?portalId=<id> — Instantly.ai API-key status / validate + save (signed). Key stored encrypted; never returned.
• GET /api/oauth/install — starts the OAuth install (redirects to the HubSpot consent screen; sets a one-time CSRF state cookie).
• GET /api/oauth/callback — OAuth redirect target; verifies state, exchanges the code, and stores the portal’s tokens.

Authentication

The cards and settings endpoints require a valid X-HubSpot-Signature-v3 header plus a X-HubSpot-Request-Timestamp within a 5-minute window, and a ?portalId that resolves to a configured portal — unsigned/direct browser requests get 401 (expected). The oauth routes instead use the standard authorization-code flow, guarded by the one-time state cookie.

Auth model

• Inbound (HubSpot → App): v3 HMAC signature validated with the app Client Secret.
• Outbound (App → HubSpot): OAuth access tokens — per-portal, auto-refreshed, with refresh tokens encrypted at rest. No static Service Key.