> ## Documentation Index > Fetch the complete documentation index at: https://docs.alysio.ai/llms.txt > Use this file to discover all available pages before exploring further. # HubSpot > Connect Alysio to HubSpot CRM using OAuth 2.0 via Paragon Connect ## Overview The HubSpot integration connects Alysio to HubSpot CRM through OAuth 2.0 using Paragon Connect. This integration supports secure, scoped read and write access to CRM data so revenue teams can query, analyze, and update HubSpot from within Alysio. Alysio can read and write CRM records such as contacts, companies, deals, tasks, notes, emails, meetings, and calls. Write access enables fast workflows like updating fields, logging activity, creating records, and keeping pipeline data current from conversational prompts. Alysio respects user-granted scopes at all times. Users can only perform the operations their HubSpot authorization permits. *** ## Primary Use Cases Use the HubSpot integration to: Query and analyze HubSpot CRM data through Alysio’s conversational interface\ Create and update HubSpot CRM records from natural language prompts\ Log activity such as notes, calls, meetings, and emails\ Sync HubSpot users and owners for provisioning and mapping\ Support cross-tool visibility by combining HubSpot with other connected systems\ Keep pipeline operations moving without switching tools *** ## Supported HubSpot Objects Alysio can work with the following HubSpot CRM objects through this integration: Contacts\ Companies\ Deals\ Tasks\ Notes\ Emails\ Meetings\ Calls Depending on scopes granted, Alysio may also access supporting metadata such as users, owners, pipelines, stages, and object properties. *** ## Authentication ### Method **OAuth 2.0 via Paragon Connect** ### Redirect URI [https://passport.useparagon.com/oauth](https://passport.useparagon.com/oauth) ### Token Handling and Security Model OAuth tokens are issued by HubSpot and managed by Paragon. Alysio does not store HubSpot OAuth tokens.\ Paragon stores and refreshes tokens securely.\ Each tenant connection is isolated using a signed X Paragon Credential header.\ Tokens are automatically refreshed through Paragon.\ When the integration is uninstalled, Paragon removes credentials and HubSpot access stops immediately.\ Alysio enforces only the scopes granted during authorization. *** ## Required Scopes The HubSpot integration uses the following scopes. ### Required scopes crm.objects.companies.read\ crm.objects.companies.write\ crm.objects.contacts.read\ crm.objects.contacts.write\ crm.objects.deals.read\ crm.objects.deals.write\ crm.objects.owners.read\ crm.objects.users.read\ crm.schemas.custom.read\ oauth\ sales-email-read\ settings.users.read\ settings.users.teams.read ### Optional scope timeline *** ## Scope Justification crm objects contacts read write\ Read, create, and update contact records crm objects companies read write\ Read, create, and update company records for account based workflows crm objects deals read write\ Retrieve, create, and update deal data for pipeline execution timeline\ Read HubSpot engagement timeline for activity visibility and analysis sales email read\ Read sales email engagement data when enabled oauth\ Required for OAuth authorization crm objects owners read and crm objects users read\ Map HubSpot owners and users to Alysio workspace identities schemas custom read\ Detect and interpret custom properties and CRM schema dynamically settings users read and settings users teams read\ Sync user and team hierarchy for provisioning and permission mapping *** ## API Usage All HubSpot API requests route through Paragon’s secure proxy: /sdk/proxy/hubspot/[https://api.hubapi.com](https://api.hubapi.com) Alysio performs read and write operations but does not delete CRM data through this integration. *** ## Read Endpoints Used Account info\ GET /account-info/v3/details\ Retrieve connected HubSpot account details Owners\ GET /crm/v3/owners\ List CRM owners for mapping and assignment Users and roles\ GET /settings/v3/users\ GET /settings/v3/users/roles\ Retrieve users, roles, and access structure CRM object search\ POST /crm/v3/objects/{object_type}/search\ Search records across supported object types Associations\ GET /crm/v4/objects/{from}/{id}/associations/{to}\ Retrieve relationships between CRM objects Pipelines and stages\ GET /crm/v3/pipelines/{objectType}/{pipelineId}/stages\ Retrieve pipeline stage definitions Object properties\ GET /crm/v3/properties/{object_type}\ Retrieve object metadata and property definitions *** ## Write Endpoints Used Create\ POST /crm/v3/objects/{object_type}\ Create CRM records across supported object types Update\ PATCH /crm/v3/objects/{object_type}/{id}\ Update CRM records by ID Merge companies\ POST /crm/v3/objects/companies/merge\ Merge duplicate company records Default associations\ PUT /crm/v4/objects/{from}/{fromId}/associations/default/{to}/{toId}\ Create default associations between objects *** ## Rate Limiting and Error Handling Errors are handled through a structured client error layer. HTTP status errors are surfaced as actionable errors\ Transient 5xx responses are retried when appropriate\ 204 No Content responses are treated as successful updates *** ## MCP Tools The HubSpot MCP tools list should be populated from your HubSpot MCP server implementation so this page mirrors actual tool availability inside Alysio. Recommended structure for the tools section: Tool name\ What it does in plain language\ What it reads or writes\ Example user prompts If you paste your HubSpot MCP tool list, I’ll convert it into the same tool table format used across the rest of your docs. *** ## App Behavior HubSpot API calls are triggered when users ask questions or request actions in Alysio. Requests are proxied through Paragon and executed only within granted scopes\ Updates are performed per user action and are not batch written by default\ Cached identifiers such as user\_id and owner\_id prevent duplicate mapping and preserve identity consistency\ If HubSpot marks users as archived, Alysio soft deletes corresponding local mappings\ All operations remain scoped and auditable *** ## Example Workflow User asks Create a new deal for Acme Corp Alysio validates that crm objects deals write is granted\ Alysio sends a proxied request through Paragon\ HubSpot creates the deal and returns the deal ID\ Alysio stores only the returned record identifier needed for mapping and referencing *** ## Troubleshooting ### Missing Admin Permissions If you see an error such as App Marketplace access permission set required, the connecting HubSpot user likely does not have permission to install or connect apps. Solution\ A HubSpot Super Admin can enable App Marketplace access in: Settings → Users and Teams → Permission Sets → Account → Settings Access → App Marketplace Access *** ### 401 Unauthorized The connection is missing, expired, or revoked. Solution\ Reconnect HubSpot in Alysio under Settings → Integrations *** ### 403 Forbidden The requested operation exceeds granted OAuth scopes. Solution\ Reauthorize HubSpot and ensure the required scopes were approved *** ### Legacy App Installation Conflicts If your workspace is mixing legacy installations with newer framework installs, authentication or scopes may fail unexpectedly. Solution\ Confirm the installation uses HubSpot Projects Framework 2025.2 or later and reinstall if needed *** ## Support [support@alysio.ai](mailto:support@alysio.ai) *** ## Version History June 2025\ Legacy HubSpot app created November 2025\ Migrated to HubSpot Projects Framework 2025.2 Ongoing\ Security and compliance enhancements including improved token isolation and dynamic scope validation *** ## Data Flow Summary A HubSpot user initiates OAuth authorization\ Authorization redirects through Paragon\ Paragon manages tokens and refresh and isolates credentials per tenant\ Alysio validates granted scopes before every request\ HubSpot API enforces permissions and returns data and responses Alysio cannot exceed granted scopes\ All data travels over HTTPS\ Tokens are not exposed or stored by Alysio\ On uninstall, the integration is deauthorized and sync stops immediately.