Manage portal auth/switch lifecycle hooks and stale credential recovery for stable HubSpot runtime context.
401 Unauthorized or 403 Forbidden error caused by an expired or wrong-portal token without interrupting the user's workflowhs auth completes, catching known quirks (e.g., sandbox portals returning production portal IDs)Not for: API rate limit management (use the rate limit throttle), CMS publish lifecycle (use hubspot-cms-release-operations), or incident triage (use hubspot-incident-triage-framework).
[Uninitialized] → [Authenticating] → [Active] → [Stale] → [Recovering]
↓ ↓
[Switching] [Re-authenticated]
↓
[Stale Check]
| State | Trigger | Recovery Action |
|---|---|---|
| Uninitialized | Session start, no env vars | Run hs auth or set HUBSPOT_ACCESS_TOKEN |
| Authenticating | hs auth in progress | Wait; detect postauth quirks on completion |
| Active | Token valid; portal ID confirmed | Normal operations |
| Stale | 401 response or >2h since last auth | Re-auth or token refresh |
| Switching | User targets a different portal ID | Flush cached portal context; re-validate |
HUBSPOT_ACCESS_TOKEN and HUBSPOT_PORTAL_ID environment variables. If either is absent, emit a structured warning and pause before the first HubSpot tool call.hs auth completes, call GET /oauth/v1/access-tokens/{token} to verify the returned hub_id matches the expected portal ID. Flag sandbox-to-production mismatches.HUBSPOT_PORTAL_ID changes mid-session, invalidate all cached property metadata, list caches, and workflow caches. Force a live-first refresh on the next API call.HUBSPOT_REFRESH_TOKEN is available. If refresh fails, surface a clear re-authentication prompt and pause all pending HubSpot tool calls.X-HubSpot-Account-Id) matches HUBSPOT_PORTAL_ID. Mismatch → block with a portal-mismatch error code.{ts, event, fromPortalId, toPortalId, tokenAge, outcome} to logs/portal-lifecycle.jsonl for audit purposes.Use this skill for portal auth/switch lifecycle and stale credential recovery only.
Defer to hubspot-agent-governance-runtime for task safety gating and to hubspot-hook-input-contracts for hook input parsing standards.