hubspot-agency-multi-portal

HubSpot Agency Multi-Portal

Overview

Operate a fleet of HubSpot portals for agency clients without cross-portal contamination, attribution loss, or onboarding bottlenecks. This is not a getting-started guide — it is the infrastructure your agency runs on day one with client one and scales to client one hundred without revisiting.

The six production failures this skill prevents:

1. Cross-portal credential contamination — a shared HUBSPOT_ACCESS_TOKEN env var causes API writes intended for Client A to silently land in Client B's CRM. The HubSpot API does not reject the call; it accepts it. Data corruption is silent and may not be discovered for days. Per-portal credential isolation — enforced in code, not convention — is the only fix.
2. Audit trail gaps — agency billing, SLA compliance, and GDPR/CCPA data-processing agreements all require proof of which API calls were made on behalf of which client. A shared token makes post-hoc attribution impossible. A per-portal structured audit log with portalId, clientSlug, operation, and timestamp makes attribution irrefutable.
3. Bulk onboarding bottleneck — onboarding 50 new clients one-at-a-time requires 50 manual credential setups, 50 manual verifications, and 50 opportunities for human error. A scriptable bulk onboarding workflow reads a CSV of client names and tokens, validates each against the account-info endpoint, and seeds the credential store in one pass.
4. Token rotation cascade — rotating one client's private-app token in HubSpot does not update any downstream system. With 50 portals, a partial rotation — some systems updated, some not — leaves stale tokens in production for undetermined periods. A per-portal rotation runbook with a cross-system checklist closes the gap.
5. Rate-limit aggregation confusion — each portal has its own independent 500K/day quota. An agency analytics system reading all 50 portals is NOT limited to 500K calls total — it has 500K per portal per day, but only if the token used for each portal belongs to that portal. A shared token collapses all quota attribution to one portal, causing artificial exhaustion and incorrect monitoring.
6. Compliance reporting ambiguity — under GDPR Article 30 and CCPA, a data processor (the agency) must demonstrate which operations were performed on which controller's (client's) data and when. A shared token makes this demonstration impossible after the fact. Per-portal audit logs with structured fields make it a simple query.

Prerequisites

• Node.js 18+ or Python 3.10+
• One HubSpot private-app token per client portal (Settings → Integrations → Private Apps → Create private app → Auth tab)
• A secret store the credential router can read at startup: AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or pass for local development
• jq installed for CLI validation steps
• python3 with standard library only for bulk onboarding script (no external deps required)
• CSV file of client slugs and tokens for bulk onboarding (format: clientSlug,portalToken,portalId)

Instructions

Build in this order. Each section closes one production failure mode.

1. Credential store design (closes cross-portal contamination)

The credential store is a JSON map of clientSlug → token. It lives in your secret manager, never in source code or environment variables. The key insight is that clientSlug is the primary key — every operation starts by selecting a slug, which deterministically selects the token. There is no ambient credential and no fallback to a global env var.

// Shape of the credential store (stored in secret manager, NOT in git or env vars)
interface PortalCredentialStore {
  version: number; // increment on every write; used for drift detection
  portals: Record<string, PortalCredential>;
}

interface PortalCredential {
  token: string;            // HubSpot private-app token: pat-na1-...
  portalId: number;         // HubSpot portal ID — verified via account-info on onboard
  clientSlug: string;       // kebab-case client identifier: "acme-corp"
  addedAt: string;          // ISO 8601 — when this credential was seeded
  lastRotatedAt: string;    // ISO 8601 — updated on every token rotation
  datacenter: string;       // "na1" | "eu1" | "au1" — extracted from token prefix
}

// Load from secret manager at process startup — never re-read per-request
async function loadCredentialStore(): Promise<PortalCredentialStore> {
  const raw = await readSecret("hubspot/agency-portals");
  const store: PortalCredentialStore = JSON.parse(raw);
  if (!store.portals || typeof store.portals !== "object") {
    throw new Error("Credential store is malformed — missing portals map");
  }
  return store;
}

The datacenter field matters: a pat-na1-* token sent to api.hubapi.com (which routes to na1) will work, but if HubSpot migrates the portal to eu1, the token prefix changes and calls to the wrong datacenter return 404. Storing the datacenter alongside the token surfaces this mismatch immediately.

2. Portal identity verification (confirm token points to expected portal)

Every token must be verified against the GET /account-info/v3/details endpoint before being admitted to the credential store. This endpoint returns the portalId for the token's portal — which is the ground truth for "which portal does this token belong to."

interface PortalDetails {
  portalId: number;
  timeZone: string;
  currency: string;
  portalType: string; // "STANDARD" | "DEVELOPER" | "SANDBOX" | "TRIAL"
}

async function verifyPortalIdentity(
  token: string,
  expectedPortalId?: number
): Promise<PortalDetails> {
  const res = await fetch("https://api.hubapi.com/account-info/v3/details", {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (res.status === 401) {
    throw new Error("Token rejected (401) — revoked, malformed, or wrong datacenter");
  }
  if (res.status === 403) {
    throw new Error("Token lacks account-info scope — re-create private app with account-info scope");
  }
  if (!res.ok) {
    throw new Error(`account-info returned ${res.status}: ${await res.text()}`);
  }

  const details: PortalDetails = await res.json();

  if (expectedPortalId !== undefined && details.portalId !== expectedPortalId) {
    throw new Error(
      `Portal ID mismatch — token belongs to portal ${details.portalId}, ` +
      `expected ${expectedPortalId}. Token is for the wrong client.`
    );
  }

  return details;
}

Run verifyPortalIdentity during onboarding (to populate portalId in the credential store) and during rotation (to confirm the new token belongs to the same portal before committing it).

3. Per-portal HTTP client factory with audit-log middleware (closes audit trail gaps)

The client factory produces an HTTP client bound to a single portal's token. Every request made through this client is logged to the audit trail with a structured record. There is no way to make an unlogged HubSpot API call through this factory — the audit middleware is non-optional.

interface AuditRecord {
  ts: string;           // ISO 8601 timestamp
  portalId: number;
  clientSlug: string;
  method: string;       // GET | POST | PATCH | DELETE
  path: string;         // /crm/v3/objects/contacts
  statusCode: number;
  durationMs: number;
  objectType?: string;  // "contacts" | "deals" | "companies" — extracted from path
  objectId?: string;    // from path or response body
  actor: string;        // "hubspot-agency-router/2.0.0"
  rateLimitRemaining?: number; // from X-HubSpot-RateLimit-Daily-Remaining header
}

type AuditWriter = (record: AuditRecord) => void | Promise<void>;

function createPortalClient(
  credential: PortalCredential,
  auditWriter: AuditWriter
) {
  const baseUrl = "https://api.hubapi.com";

  return async function portalFetch(
    path: string,
    init: RequestInit = {}
  ): Promise<Response> {
    const start = Date.now();
    const method = (init.method ?? "GET").toUpperCase();

    const res = await fetch(`${baseUrl}${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${credential.token}`,
        "Content-Type": "application/json",
        ...init.headers,
      },
    });

    const durationMs = Date.now() - start;
    const objectType = extractObjectType(path);
    const objectId = extractObjectId(path);

    const record: AuditRecord = {
      ts: new Date().toISOString(),
      portalId: credential.portalId,
      clientSlug: credential.clientSlug,
      method,
      path,
      statusCode: res.status,
      durationMs,
      objectType,
      objectId,
      actor: "hubspot-agency-router/2.0.0",
      rateLimitRemaining: parseInt(
        res.headers.get("X-HubSpot-RateLimit-Daily-Remaining") ?? "0",
        10
      ),
    };

    // Fire-and-forget — do not block the response on audit write
    Promise.resolve(auditWriter(record)).catch((err) => {
      console.error("Audit write failed — call was NOT prevented:", err);
    });

    return res;
  };
}

function extractObjectType(path: string): string | undefined {
  const match = path.match(/\/crm\/v\d+\/objects\/([^/?]+)/);
  return match?.[1];
}

function extractObjectId(path: string): string | undefined {
  const match = path.match(/\/crm\/v\d+\/objects\/[^/?]+\/(\d+)/);
  return match?.[1];
}

The audit writer can be any function that accepts an AuditRecord — write to stdout (structured JSON), append to a file, push to a database, or forward to a logging pipeline. The factory does not care.

4. Router class (ties credentials + audit + identity together)

class HubSpotAgencyRouter {
  private store: PortalCredentialStore;
  private clientCache = new Map<string, ReturnType<typeof createPortalClient>>();
  private auditWriter: AuditWriter;

  constructor(store: PortalCredentialStore, auditWriter: AuditWriter) {
    this.store = store;
    this.auditWriter = auditWriter;
  }

  getClient(clientSlug: string): ReturnType<typeof createPortalClient> {
    if (!this.store.portals[clientSlug]) {
      throw new Error(
        `No credential found for client slug "${clientSlug}". ` +
        `Available slugs: ${Object.keys(this.store.portals).join(", ")}`
      );
    }
    if (!this.clientCache.has(clientSlug)) {
      this.clientCache.set(
        clientSlug,
        createPortalClient(this.store.portals[clientSlug], this.auditWriter)
      );
    }
    return this.clientCache.get(clientSlug)!;
  }

  listClients(): string[] {
    return Object.keys(this.store.portals).sort();
  }

  getPortalId(clientSlug: string): number {
    const cred = this.store.portals[clientSlug];
    if (!cred) throw new Error(`Unknown client slug: ${clientSlug}`);
    return cred.portalId;
  }
}

// Startup
const store = await loadCredentialStore();
const router = new HubSpotAgencyRouter(store, (record) => {
  process.stdout.write(JSON.stringify(record) + "\n");
});

// Usage — every call is slug-scoped; no ambient credential
const client = router.getClient("acme-corp");
const contacts = await client("/crm/v3/objects/contacts?limit=10");

5. Rate-limit attribution (closes quota confusion)

Each portal's 500K daily quota is tracked independently by HubSpot — but only if the token used for each portal belongs exclusively to that portal. A shared token collapses all quota into the token's home portal, making the remaining-quota header meaningless for any client except the token's owner.

Read the X-HubSpot-RateLimit-Daily-Remaining header from every response and log it with the clientSlug. When any portal's remaining quota drops below a threshold, throttle that portal's calls — not the agency's calls globally.

const RATE_LIMIT_WARN_THRESHOLD = 50_000; // warn at 50K remaining of 500K daily

// Inside the audit writer
function checkRateLimit(record: AuditRecord): void {
  if (
    record.rateLimitRemaining !== undefined &&
    record.rateLimitRemaining < RATE_LIMIT_WARN_THRESHOLD
  ) {
    console.warn(JSON.stringify({
      event: "rate_limit_warning",
      clientSlug: record.clientSlug,
      portalId: record.portalId,
      dailyRemaining: record.rateLimitRemaining,
      threshold: RATE_LIMIT_WARN_THRESHOLD,
    }));
  }
}

6. Bulk onboarding script (closes the bottleneck)

The bulk onboarding script reads a CSV of client slugs, HubSpot tokens, and expected portal IDs. It validates each token against account-info/v3/details, confirms portal identity, and seeds the credential store. See references/implementation-guide.md for the full Python implementation.

Quick-verify a single portal from the CLI before seeding:

# Verify a token returns the expected portal ID
TOKEN="pat-na1-your-token-here"
EXPECTED_PORTAL_ID="12345678"

curl -s "https://api.hubapi.com/account-info/v3/details" \
  -H "Authorization: Bearer $TOKEN" | \
  jq --argjson expected "$EXPECTED_PORTAL_ID" '
    if .portalId == $expected
    then "OK — portal \(.portalId) (\(.portalType))"
    else "MISMATCH — token belongs to portal \(.portalId), expected \($expected)"
    end
  '

7. Token rotation runbook (closes the cascade problem)

HubSpot does not offer an API for rotating private-app tokens. Rotation happens in the HubSpot Settings UI, which immediately revokes the old token and generates a new one. The cascade problem is that with 50 portals, any system that stored the old token (secret manager, CI secrets, staging environment, webhook receiver) must be updated before the old token is revoked — or it will fail immediately.

Rotation order matters: update all consuming systems BEFORE revoking the old token in HubSpot.

See references/implementation-guide.md for the per-portal rotation runbook with a cross-system checklist.

Error Handling

HTTP Status	Error	Root Cause	Action
200 OK with wrong portalId	Identity mismatch on account-info	Token belongs to a different portal than expected	Reject the token; do not admit to credential store; flag for human review
401 UNAUTHORIZED	INVALID_AUTHENTICATION	Token revoked, malformed, or sent to wrong datacenter endpoint	Verify token format matches datacenter; check if a rotation left stale token in store
403 FORBIDDEN	MISSING_SCOPES	Private app does not have the required scope	Re-create private app with correct scopes; update token in credential store
403 FORBIDDEN	PORTAL_SUSPENDED	Client portal is suspended or deactivated	Contact client; stop all calls for this slug
404 NOT_FOUND	Resource does not exist	Object ID does not exist in this portal	Normal — handle in application logic; log objectType and objectId for audit
429 TOO_MANY_REQUESTS	RATE_LIMIT	Portal's 500K daily quota exhausted	Back off with Retry-After; alert on daily-remaining; do NOT retry blind
429 TOO_MANY_REQUESTS	TEN_SECONDLY_ROLLING	100–150 calls/10s burst limit hit	Exponential backoff with jitter; this is per-portal, not per-agency
503 SERVICE_UNAVAILABLE	HubSpot outage	HubSpot API unavailable	Back off with jitter; check status.hubspot.com; do not rotate credentials

Cross-portal contamination detection

If a write operation (POST/PATCH/DELETE) succeeds but the response body's portalId (available on some endpoints) does not match the expected portal, you have a contamination event. Stop immediately:

async function assertPortalSafety(
  response: Response,
  expectedPortalId: number,
  clientSlug: string
): Promise<void> {
  const body = await response.clone().json().catch(() => null);
  if (body?.portalId && body.portalId !== expectedPortalId) {
    throw new Error(
      `CRITICAL: Cross-portal contamination detected. ` +
      `Write intended for portal ${expectedPortalId} (${clientSlug}) ` +
      `landed in portal ${body.portalId}. ` +
      `Halt all operations and audit credential store immediately.`
    );
  }
}

Examples

Onboard a single client portal

# 1. Verify the token belongs to the expected portal
TOKEN="pat-na1-abc123..."
EXPECTED="12345678"
curl -s "https://api.hubapi.com/account-info/v3/details" \
  -H "Authorization: Bearer $TOKEN" | jq '{portalId, portalType, currency}'

# 2. Add to credential store (read existing, append, write back)
STORE=$(pass show hubspot/agency-portals | python3 -c "import sys,json; d=json.load(sys.stdin); \
  d['portals']['new-client']={'token':'$TOKEN','portalId':$EXPECTED,'clientSlug':'new-client',\
  'addedAt':'$(date -u +%Y-%m-%dT%H:%M:%SZ)','lastRotatedAt':'$(date -u +%Y-%m-%dT%H:%M:%SZ)',\
  'datacenter':'na1'}; d['version']+=1; print(json.dumps(d))" )
echo "$STORE" | pass insert -e hubspot/agency-portals

Bulk onboard from CSV

# clients.csv format: clientSlug,portalToken,expectedPortalId
# acme-corp,pat-na1-abc...,12345678
# beta-inc,pat-eu1-def...,87654321

python3 references/bulk-onboard.py \
  --csv clients.csv \
  --secret-backend pass \
  --secret-path hubspot/agency-portals \
  --dry-run  # remove --dry-run to commit

Generate a per-client compliance report

# Summarize API calls for acme-corp in May 2026
python3 references/compliance-report.py \
  --audit-log /var/log/hubspot-agency/audit.jsonl \
  --client-slug acme-corp \
  --from 2026-01-01 \
  --to 2026-01-31 \
  --output acme-corp-jan-2026-compliance.csv

Rate limit check across all portals

# Poll account-info for each portal and report daily remaining
for slug in $(pass show hubspot/agency-portals | jq -r '.portals | keys[]'); do
  TOKEN=$(pass show hubspot/agency-portals | jq -r ".portals[\"$slug\"].token")
  REMAINING=$(curl -si "https://api.hubapi.com/crm/v3/objects/contacts?limit=1" \
    -H "Authorization: Bearer $TOKEN" | grep -i x-hubspot-ratelimit-daily-remaining | awk '{print $2}' | tr -d '\r')
  echo "$slug: $REMAINING remaining"
done

Output

• Credential store seeded with per-portal records, each verified against account-info/v3/details
• Per-portal HTTP client factory with audit-log middleware on every call
• Structured audit log emitting JSON records with portalId, clientSlug, method, path, statusCode, durationMs, rateLimitRemaining
• Rate-limit warnings per portal when daily remaining drops below configurable threshold
• Bulk onboarding script that validates and seeds 10-100 portals from a CSV in a single pass
• Token rotation runbook with cross-system checklist preventing partial rotation
• Compliance report generator producing per-client call counts by date range from audit logs

Resources

• HubSpot Account Info API
• HubSpot Private Apps Guide
• Rate Limits Reference
• GDPR and HubSpot Data Processing
• API_REFERENCE.md — account-info endpoint shape, per-portal rate limit headers, audit log schema
• implementation-guide.md — credential store design, bulk onboarding script, rotation runbook, compliance report generator