Hubspot Portal Runtime Lifecycle

[Uninitialized] → [Authenticating] → [Active] → [Stale] → [Recovering]
                                         ↓                      ↓
                                    [Switching]           [Re-authenticated]
                                         ↓
                                   [Stale Check]

Workflow

1. Session initialization hook — on session start, check for 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.
2. Postauth quirk detection — after 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.
3. Portal switch staleness check — when 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.
4. Stale credential recovery — on a 401 response, attempt a token refresh if HUBSPOT_REFRESH_TOKEN is available. If refresh fails, surface a clear re-authentication prompt and pause all pending HubSpot tool calls.
5. Lifecycle guardrail enforcement — before any write operation, confirm the runtime portal ID (from the API response header X-HubSpot-Account-Id) matches HUBSPOT_PORTAL_ID. Mismatch → block with a portal-mismatch error code.
6. Log lifecycle transitions — write {ts, event, fromPortalId, toPortalId, tokenAge, outcome} to logs/portal-lifecycle.jsonl for audit purposes.

Routing Boundaries

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.

References

• Postauth Quirk Detection
• Portal Switch Staleness Handling
• Portal Lifecycle Guardrails