Skip to main content
Connect to HubSpot CRM using OAuth 2.0
This guide walks you through connecting your HubSpot account to Ravenna for CRM data access.

​
Prerequisites

Before you begin, ensure you have:
  • A HubSpot account with CRM access
  • Admin or super admin permissions in HubSpot
  • Organization admin access in Ravenna

​
Required permissions

The HubSpot integration requires the following OAuth scopes:
These are read-only permissions. Ravenna does not create, modify, or delete any data in your HubSpot account.

​
Setup guide

1

Navigate to integrations

  1. Go to Settings > Integrations
  2. Find HubSpot in the CRM section
2

Start OAuth flow

Click Connect with HubSpot to begin the authorization process.You’ll be redirected to HubSpot to authorize the connection.
3

Authorize access

  1. Sign in to HubSpot if prompted
  2. Select the HubSpot account you want to connect
  3. Review the requested permissions
  4. Click Connect app to authorize Ravenna
Make sure you select the correct HubSpot portal if you have access to multiple accounts.
4

Complete setup

After authorization, you’ll be redirected back to Ravenna. The integration will:
  1. Validate the OAuth tokens
  2. Fetch your HubSpot portal information
  3. Enable HubSpot agent tools
You’ll see a confirmation that HubSpot is connected.

​
Enable agent tools

After connecting HubSpot, enable the tools on your AI agents:
1

Navigate to agent settings

Go to Settings > AI > Agents or your workspace agent configuration.
2

Enable HubSpot tools

Toggle on the HubSpot tools you want your agent to use:
  • List Deals - For browsing recent deals
  • Search Deals - For filtered deal queries
  • Get Deal - For detailed deal information
  • Search Companies - For company lookups
  • List Owners - For owner/user lookups
  • Search Contacts - For contact lookups
3

Test the integration

Try asking your agent questions like:
  • “Show me recent deals”
  • “What are our high priority deals?”
  • “Find deals for ABC Company”
  • “Who owns the XYZ deal?”

​
Troubleshooting

Cause: Authorization was denied or failed during the OAuth flowSolution:
  • Ensure you have admin permissions in HubSpot
  • Check that you selected the correct HubSpot portal
  • Try the connection process again
  • Clear browser cookies and cache if issues persist
Cause: Your HubSpot user doesn’t have access to required CRM dataSolution:
  • Verify you have CRM access in your HubSpot account
  • Check with your HubSpot admin about user permissions
  • Ensure the connected portal has the required HubSpot subscription tier
Cause: The search returned no resultsSolution:
  • Verify deals exist in your HubSpot account
  • Check that the search filters match existing data
  • Try broader search criteria
  • Ensure the connected HubSpot portal is the correct one
Cause: Deals don’t have associated companies in HubSpotSolution:
  • Associate companies with deals in HubSpot
  • Check that company records exist in your HubSpot account
  • Verify associations are set up correctly in HubSpot
Cause: OAuth access token has expiredSolution:
  • Ravenna automatically refreshes tokens, but if issues persist:
  • Disconnect and reconnect the HubSpot integration
  • Check that your HubSpot account is still active

​
Data access

Ravenna accesses HubSpot data in real-time. There is no data sync or storage of your CRM data in Ravenna.
When an agent uses HubSpot tools:
  1. The query is sent to HubSpot’s API
  2. Results are returned and formatted for the agent
  3. The agent uses the data to answer the user’s question
  4. No CRM data is stored in Ravenna
Last modified on April 30, 2026