hubspot-agency-multi-portal

What it does

Implements credential isolation for 10-100 HubSpot portals, with per-portal audit trails and a scriptable bulk onboarding workflow. Provides a router that ties credentials, audit logging, and portal identity together, and a per-portal HTTP client with mandatory audit logging.

How it works

• Credential store design keeps a JSON map of clientSlug → token in a secret manager; each operation selects a slug to deterministically choose the token. The store includes portalId, clientSlug, addedAt, lastRotatedAt, and datacenter for datacenter alignment.
• Portal identity verification checks the token against GET /account-info/v3/details to obtain portalId and validate it against the expected portal, returning details such as portalId, timeZone, currency, and portalType.
• A per-portal HTTP client factory binds API calls to a single portal's token and logs every request to an audit trail with fields like ts, portalId, clientSlug, method, path, statusCode, durationMs, objectType, objectId, actor, and rateLimitRemaining. It extracts objectType and objectId from the path.
• The Router class ties credentials, audit, and identity: it caches portal-specific clients per clientSlug, lists known slugs, and exposes a getPortalId helper. Startup loads the credential store and wires an auditWriter (stdout JSON) into the router.
• Rate-limit attribution tracks X-HubSpot-RateLimit-Daily-Remaining per response and logs a rate-limit warning when remaining falls below a threshold, throttling per-portal usage based on the remaining quota.
• Bulk onboarding reads a CSV of client slugs, tokens, and portal IDs; validates tokens via account-info/v3/details, confirms portal identity, and seeds the credential store. A quick-verify CLI example shows how to check a token against an expected portal ID.

When to use it

Use when onboarding new client portals, building per-client API call logs for GDPR/CCPA attribution, rotating tokens across an agency fleet, or generating per-client compliance reports. Trigger phrases include: "hubspot agency", "multi-portal management", "hubspot credential isolation", "per-portal audit log", "hubspot compliance report", "bulk portal onboarding", "token rotation cascade".

What it can touch

• Reads and writes to the secret-based credential store (portal credentials: token, portalId, clientSlug, addedAt, lastRotatedAt, datacenter).
• Performs HTTP requests to HubSpot API endpoints via a per-portal client bound to each credential.
• Emits audit records to an auditWriter (e.g., stdout, file, DB, or logging pipeline).
• Reads response headers (X-HubSpot-RateLimit-Daily-Remaining) for rate-limit tracking.

Caveats

• Rotation is manual via HubSpot UI; this tool documents a rotation runbook and recommends updating consuming systems before revoking old tokens.
• Requires per-client tokens and a secret store; misconfiguration can lead to cross-portal contamination or broken audits if the store or identity checks fail.
• The audit logging is non-optional; all calls are logged through the portal client factory.