Reconnecting a Portal
Portal connections in JetStack AI rely on OAuth tokens that can expire or become invalidated. When this happens, the portal’s connection status changes and you need to re-authorize. Reconnecting is a quick process that restores full access without losing any previously imported assets or configuration.
Connection Status Indicators
Section titled “Connection Status Indicators”Every portal in the Client Accounts table displays a status indicator showing the health of the OAuth connection:
| Status | Indicator | Meaning |
|---|---|---|
| Connected | Green | The OAuth connection is active and all tokens are valid. JetStack AI can make API calls to this portal. |
| Needs Reconnection | Yellow | The OAuth token has expired or scopes have changed. JetStack AI cannot make API calls until you re-authorize. |
| Disconnected | Red | The connection has been fully revoked, either from JetStack AI or from HubSpot’s side. Requires a new OAuth flow. |
A yellow Needs Reconnection status is the most common situation. It does not mean anything is broken — it simply means the authorization needs to be refreshed.
Why Portals Need Reconnection
Section titled “Why Portals Need Reconnection”Several situations can cause a portal to enter the Needs Reconnection state:
- Token expiry — HubSpot refresh tokens can become invalid if the authorizing user’s permissions change or if HubSpot rotates tokens on their end.
- Scope changes — If JetStack AI adds new features that require additional OAuth scopes, existing connections need to be re-authorized with the updated scope set.
- User deactivation — If the HubSpot user who originally authorized the connection is deactivated or has their permissions downgraded, the OAuth tokens tied to that user become invalid.
- Manual revocation in HubSpot — If someone removes JetStack AI from Settings > Integrations > Connected Apps in HubSpot, the tokens are immediately invalidated.
- HubSpot account changes — Portal merges, downgrades, or subscription changes on the HubSpot side can invalidate existing OAuth connections.
How to Reconnect
Section titled “How to Reconnect”- Navigate to Client Accounts in the left sidebar.
- Locate the portal with a yellow or red status indicator in the table.
- Click the Reconnect button in the Actions column for that portal.
- You are redirected to HubSpot’s OAuth authorization screen. Select the same portal and review the requested permissions.
- Click Connect app to authorize.
- HubSpot redirects you back to JetStack AI. The portal status updates to Connected (green).
The reconnection flow is identical to the initial connection flow. JetStack AI replaces the expired tokens with fresh ones and resumes normal operation.
What Reconnection Preserves
Section titled “What Reconnection Preserves”Reconnecting a portal does not reset or delete any of the following:
- Imported assets — All assets previously imported from this portal remain in your JetStack AI library.
- Deployment history — Records of past deployments to or from this portal are retained.
- Activity history — All tasks, logs, and error details associated with this portal stay intact.
- Connection type — The portal’s connection type (Config Only, Config + Audit, Audit Only) is preserved. You do not need to reconfigure it.
Reconnection only refreshes the OAuth tokens. Everything else remains unchanged.
What Happens if You Ignore It
Section titled “What Happens if You Ignore It”If a portal stays in the Needs Reconnection state:
- Imports from this portal will fail immediately with an authentication error.
- Deployments to this portal will fail at the first API call.
- Audits on this portal cannot be started.
- Existing data is unaffected — previously imported assets and completed audits remain available.
There is no deadline or expiration for reconnecting. The portal will remain in the yellow state indefinitely until you either reconnect or remove it.
Reconnection Requirements
Section titled “Reconnection Requirements”The person completing the reconnection must have:
- HubSpot Admin access on the portal being reconnected (Super Admin or Admin role)
- JetStack AI account access with permission to manage portals in the organization
The reconnecting user does not need to be the same person who originally authorized the connection. Any Admin on both the HubSpot portal and the JetStack AI organization can complete the flow.
Troubleshooting
Section titled “Troubleshooting”If reconnection fails, see OAuth Connection Flow for details on the authorization process. Common issues include pop-up blockers interfering with the redirect, insufficient HubSpot permissions, or temporary HubSpot OAuth service disruptions. For persistent issues, see Connection & OAuth Troubleshooting.