HubSpot Auth

Overview

Authenticate a service to HubSpot and operate the auth layer in production. This is not a setup walkthrough — it is the auth code your integration runs at 3am when an OAuth token expires mid-batch, when a portal admin removes a scope, when an agency credential router sends a request to the wrong portal, and when on-call needs to rotate a leaked private-app token without dropping in-flight requests.

The six production failures this skill prevents:

1. Token expiry storms — OAuth access tokens expire in 1800 seconds. Every concurrent request notices expiry simultaneously, races to refresh, the token endpoint rate-limits at 10 auth calls/10s, the integration cascades to red.
2. Daily rate-limit burnout — retry storms on auth failures burn through the 500K daily API call quota before noon. Exponential backoff with jitter is non-optional.
3. Scope drift — a portal admin edits the private app's scopes or a connected OAuth app loses authorization. Cached tokens start returning 403. Retrying does not help.
4. Token leakage in commits — pat-na1-* private-app tokens are wide-scope and not auto-expiring. A single leaked commit exposes the entire portal.
5. Multi-portal credential routing — agencies managing 50+ portals cannot use a single HUBSPOT_ACCESS_TOKEN. Requests sent to the wrong portal silently operate on the wrong data.
6. OAuth refresh-token decay — HubSpot refresh tokens expire after one year of non-use. Integrations that go idle (seasonal products, paused automations) silently lose access and require user reconnection.

Prerequisites