HubSpot

Connect Alysio to HubSpot CRM using OAuth 2.0 via Paragon Connect

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

Scope	Purpose
crm.objects.contacts.read / write	Read, create, and update contact records.
crm.objects.companies.read / write	Manage company data for account-based insights.
crm.objects.deals.read / write	Retrieve and update deal information.
timeline	Access HubSpot engagement timeline for activity analysis.
sales-email-read	Read sales emails for engagement insights.
oauth	Required for OAuth authentication.
crm.objects.owners.read / users.read	Map HubSpot owners and users to Alysio accounts.
leads.read / write	Optional lead import and enrichment.
marketing.campaigns.read / marketing_events.read	Optional analytics enrichment.
schemas.custom.read	Detect custom CRM objects dynamically.
settings.users.*	Sync HubSpot team and user hierarchy.
content	Optional 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

Category	Endpoint	Purpose
Account	/account-info/v3/details	Retrieve account info
Owners	/crm/v3/owners	List CRM owners
Users	/settings/v3/users, /settings/v3/users/roles	Fetch users and roles
Objects	/crm/v3/objects/{object_type}/search	Search CRM records
Associations	/crm/v4/objects/{from}/{id}/associations/{to}	Retrieve relationships
Pipelines	/crm/v3/pipelines/{objectType}/{pipelineId}/stages	Get pipeline stages
Properties	/crm/v3/properties/{object_type}	Get object property metadata

Write Endpoints

Operation	Endpoint	Description
Create	POST /crm/v3/objects/{object_type}	Create records for all 8 object types
Update	PATCH /crm/v3/objects/{object_type}/{id}	Update existing CRM objects
Merge	POST /crm/v3/objects/companies/merge	Merge duplicate companies
Associate	PUT /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

• Email: [e-mail]

• Docs: https://tech.alysio.ai/integrations/hubspot

---

Version History

Date	Update	Notes
June 2025	Legacy HubSpot App Created	Initial app built under HubSpot’s legacy app framework
November 2025	Migrated to HubSpot Projects Framework 2025.2	Upgraded to HubSpot’s new developer platform with updated OAuth handling, redirect validation, and improved scope management
Ongoing	Security and Compliance Enhancements	Continued 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.