Skip to main content

​
Overview

The HubSpot integration connects Alysio to HubSpot CRM using OAuth 2.0 via Paragon Connect. It allows secure two-way communication for reading and writing CRM data — including contacts, companies, deals, tasks, notes, emails, meetings, and calls — while respecting all user-granted OAuth scopes.
Read & Write Access: This integration supports both reading and writing data, making it ideal for updating fields, logging notes, and managing your pipeline on the fly.
Purpose & Use Cases
  • Query, analyze, and update HubSpot data through Alysio’s AI chat interface
  • Create and update CRM records directly from conversational prompts
  • Sync users and owners for workspace provisioning and role assignment
  • Enrich CRM data and unify cross-tool visibility
Supported HubSpot Objects
  • Contacts
  • Companies
  • Deals
  • Tasks
  • Notes
  • Emails
  • Meetings
  • Calls

​
Authentication

Method: OAuth 2.0 via Paragon Connect Redirect URI: https://passport.useparagon.com/oauth Token Handling:
  • OAuth tokens are issued by HubSpot and securely managed by Paragon; Alysio never stores them.
  • Each tenant connection is isolated by a signed X-Paragon-Credential header.
  • Tokens are automatically refreshed through Paragon.
  • Upon uninstall, credentials are removed and all API access stops.
  • Alysio dynamically enforces user-granted OAuth scopes — users can perform only the operations their HubSpot token permits.
App Marketplace Access: If you see an error stating “App Marketplace access permission set required,” it means your HubSpot user doesn’t have permission to install or connect apps. A HubSpot Super Admin needs to enable this by going to Settings → Users & Teams → Permission Sets → Account → Settings Access, then turning on App Marketplace Access.
Required Scopes 
crm.objects.contacts.write
timeline
sales-email-read
oauth
crm.objects.companies.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.contacts.read
Optional Scopes 
crm.objects.users.read
content
crm.objects.marketing_events.read
crm.schemas.custom.read
marketing.campaigns.read
crm.objects.owners.read
settings.users.teams.read
settings.users.read
crm.objects.leads.read
crm.objects.leads.write
Scope Justification
ScopePurpose
crm.objects.contacts.read / writeRead, create, and update contact records.
crm.objects.companies.read / writeManage company data for account-based insights.
crm.objects.deals.read / writeRetrieve and update deal information.
timelineAccess HubSpot engagement timeline for activity analysis.
sales-email-readRead sales emails for engagement insights.
oauthRequired for OAuth authentication.
crm.objects.owners.read / users.readMap HubSpot owners and users to Alysio accounts.
leads.read / writeOptional lead import and enrichment.
marketing.campaigns.read / marketing_events.readOptional analytics enrichment.
schemas.custom.readDetect custom CRM objects dynamically.
settings.users.*Sync HubSpot team and user hierarchy.
contentOptional read-only CMS access.

​
API Usage

All requests route through Paragon’s secure proxy (/sdk/proxy/hubspot/https://api.hubapi.com). Alysio performs both read and write operations but does not delete data. Read Endpoints
CategoryEndpointPurpose
Account/account-info/v3/detailsRetrieve account info
Owners/crm/v3/ownersList CRM owners
Users/settings/v3/users, /settings/v3/users/rolesFetch users and roles
Objects/crm/v3/objects/{object_type}/searchSearch CRM records
Associations/crm/v4/objects/{from}/{id}/associations/{to}Retrieve relationships
Pipelines/crm/v3/pipelines/{objectType}/{pipelineId}/stagesGet pipeline stages
Properties/crm/v3/properties/{object_type}Get object property metadata
Write Endpoints
OperationEndpointDescription
CreatePOST /crm/v3/objects/{object_type}Create records for all 8 object types
UpdatePATCH /crm/v3/objects/{object_type}/{id}Update existing CRM objects
MergePOST /crm/v3/objects/companies/mergeMerge duplicate companies
AssociatePUT /crm/v4/objects/{from}/{fromId}/associations/default/{to}/{toId}Create default associations
Rate Limiting & Error Handling
  • HTTP status errors handled via BaseClientError
  • Retries for transient 5xx responses
  • 204 No Content handled gracefully for update success responses

​
App Behavior

  • API calls occur on-demand from user interactions in Alysio chat or background sync triggers.
  • Data updates are proxied through Paragon and executed only within granted scopes.
  • Cached identifiers (user_id, owner_id) prevent duplicate creation and maintain mapping consistency.
  • If HubSpot marks users archived, Alysio soft-deletes corresponding local entries.
  • No batch writes — all updates are scoped and triggered per user action.
Example Flow
  1. User asks: “Create a new deal for Acme Corp.”
  2. Alysio validates that crm.objects.deals.write is granted.
  3. Alysio sends a proxied POST request through Paragon.
  4. HubSpot creates the deal; Alysio stores only the returned ID.

​
Troubleshooting

Common Issues
  • Missing scopes → App install blocked; verify HubSpot admin privileges.
  • Legacy app installs → Ensure installation uses HubSpot’s Projects Framework (v 2025.2 or later).
  • 403 Forbidden → Occurs when requested operation exceeds granted scopes.
  • 401 Unauthorized → Reauthorize connection in Alysio → Settings → Integrations.
Support

​
Version History

DateUpdateNotes
June 2025Legacy HubSpot App CreatedInitial app built under HubSpot’s legacy app framework
November 2025Migrated to HubSpot Projects Framework 2025.2Upgraded to HubSpot’s new developer platform with updated OAuth handling, redirect validation, and improved scope management
OngoingSecurity and Compliance EnhancementsContinued SOC 2 / ISO 27001 alignment, improved token isolation, and dynamic scope validation

​
Data Flow Diagram

Text Version: 
┌─────────────────┐
│  HubSpot User   │
│  Initiates      │
│  Connection     │
└────────┬────────┘
         │
         ▼
┌─────────────────────────┐
│  (1) OAuth Authorization │
│  Redirect URI:           │
│  passport.useparagon.com │
└────────┬─────────────────┘
         │
         ▼
┌─────────────────────────┐
│   Paragon Connect       │
│                         │
│  • Manages OAuth tokens │
│  • Handles token refresh│
│  • Isolates credentials  │
│    via X-Paragon-       │
│    Credential header    │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│      Alysio App         │
│                         │
│  • Validates granted    │
│    OAuth scopes         │
│  • Executes permitted   │
│    API calls            │
│  • Caches identifiers   │
│    (user_id, owner_id)  │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│     HubSpot API         │
│                         │
│  • Enforces permissions │
│  • Returns data/        │
│    responses            │
│  • Validates scopes     │
└─────────────────────────┘
Summary
  • Alysio cannot exceed the scopes granted by the user.
  • Every API call is validated against the token’s scopes before execution.
  • All data travels over HTTPS; tokens are never exposed or stored locally.
  • On uninstall, the integration is fully deauthorized and all syncs stop.