OAuth Connection Flow
JetStack AI connects to HubSpot portals exclusively through OAuth 2.0 — the same authorization standard that all HubSpot Marketplace apps use. This means no API keys are stored, no tokens are exchanged manually, and access can be revoked at any time from either JetStack AI or HubSpot.
This page covers the technical details of the OAuth flow. For the step-by-step walkthrough of adding a portal, see Adding a Portal.
How the OAuth Flow Works
Section titled “How the OAuth Flow Works”The connection follows the standard OAuth 2.0 authorization code flow:
- Initiation — You click Add Portal in JetStack AI. JetStack AI redirects your browser to HubSpot’s authorization endpoint with the requested scopes and a unique state parameter.
- Authorization — HubSpot presents its standard OAuth consent screen. You select which portal to authorize and review the permissions JetStack AI is requesting.
- Consent — You click Connect app. HubSpot generates an authorization code and redirects your browser back to JetStack AI’s callback URL.
- Token Exchange — JetStack AI’s backend exchanges the authorization code for an access token and a refresh token. This happens server-side and is not visible to you.
- Connection Established — JetStack AI stores the encrypted tokens and records the portal ID, portal name, and connection metadata. The portal appears in your Client Accounts list.
The entire flow typically completes in under 10 seconds.
Requested Scopes
Section titled “Requested Scopes”JetStack AI requests a specific set of OAuth scopes based on the features it provides. Each scope category maps to a set of HubSpot APIs:
| Scope Category | Covers | Used For |
|---|---|---|
| CRM | Contacts, companies, deals, tickets, custom objects, properties, pipelines, association labels | Importing/deploying CRM assets; reading CRM schema for audits |
| Marketing | Emails, forms, lists, workflows | Importing/deploying marketing automation assets |
| CMS | Pages, blog posts, templates, modules, HubDB tables, files | Importing/deploying website content and CMS assets |
| Automation | Workflows, sequences | Reading and deploying workflow configurations |
| Reporting | Dashboards, reports | Importing/deploying reporting assets (Ultimate plan) |
| Settings | Account settings, users, teams | Reading portal configuration for audits |
| Files | File manager | Uploading images and documents during deployment |
All scopes are requested upfront during the initial connection. This prevents the need for re-authorization when you use a new feature for the first time.
Token Management
Section titled “Token Management”JetStack AI handles token lifecycle automatically:
- Access tokens expire after 30 minutes (set by HubSpot). JetStack AI refreshes them automatically using the refresh token before making API calls.
- Refresh tokens do not expire on their own but can be invalidated if the authorizing user revokes access or if scopes change on HubSpot’s side.
- Token storage — All tokens are encrypted at rest and stored in JetStack AI’s backend. Tokens are never exposed to the browser or included in client-side code.
If a refresh token becomes invalid, the portal’s connection status changes to Needs Reconnection (yellow indicator). See Reconnecting a Portal for how to resolve this.
Security Model
Section titled “Security Model”JetStack AI’s OAuth implementation follows these security principles:
- Server-side token exchange — Authorization codes are exchanged for tokens on JetStack AI’s backend, never in the browser.
- State parameter validation — Every OAuth flow includes a unique, cryptographically random state parameter to prevent CSRF attacks.
- Encrypted storage — Tokens are encrypted at rest using AES-256 encryption.
- Minimal retention — If you remove a portal, the associated tokens are deleted immediately.
- No shared credentials — Each portal connection uses its own independent OAuth tokens. Connecting or disconnecting one portal has no effect on others.
Revoking Access
Section titled “Revoking Access”You can revoke JetStack AI’s access to a portal from two places:
- From JetStack AI — Remove the portal from your Client Accounts list. This deletes the stored tokens and disconnects JetStack AI.
- From HubSpot — Go to Settings > Integrations > Connected Apps in HubSpot and remove JetStack AI. This invalidates the tokens. The portal will show as Disconnected (red) in JetStack AI the next time it attempts an API call.
Revoking access does not delete any assets that were previously imported into your JetStack AI library. It only prevents future API calls to that portal.
Scope Changes
Section titled “Scope Changes”If HubSpot introduces new scopes or JetStack AI adds features requiring additional permissions, you may need to re-authorize. In this case, the portal status will change to Needs Reconnection and you will be prompted to complete a new OAuth flow that includes the updated scopes.
Re-authorization preserves your existing portal connection and all associated data. It simply refreshes the OAuth tokens with the new scope set.