HubSpot Customer Intelligence OAuth App

⚠️ DEPRECATED: This repository has been consolidated into the main HubSpot Intelligence MCP repository.

➡️ Please use the main repository which includes:

• Complete MCP server with 6 customer intelligence tools
• This OAuth app (in the hubspot-app/ directory)
• One-click deployment scripts
• Comprehensive documentation

🔗 Go to: https://github.com/DripEmail/hubspot-intelligence-mcp

---

📦 Archive Status

Repository Status: ARCHIVED
Migration Date: September 11, 2025
Migration Reason: Consolidated into main MCP repository for better user experience

What Was Migrated:

• ✅ OAuth app configuration (app-hsmeta.json)
• ✅ HubSpot project configuration (hsproject.json)
• ✅ All required scopes including conversations.read
• ✅ Deployment scripts and documentation
• ✅ Professional support contact information

Benefits of Consolidation:

• Single repository for complete customer intelligence platform
• No separate OAuth app setup required - everything included
• Streamlined deployment with one-click scripts
• Better documentation with integrated setup guides

---

Legacy Documentation

A HubSpot OAuth application enabling secure access to customer intelligence data, including email communications that are typically restricted.

Purpose

Solves "User does not have permissions to view emails" errors by providing proper OAuth scopes for comprehensive HubSpot CRM data access. Enables external systems to query complete customer relationships across contacts, companies, deals, emails, and support tickets.

Quick Start

Deploy to HubSpot

git clone https://github.com/DripEmail/hubspot-customer-intelligence-oauth.git
cd hubspot-customer-intelligence-oauth
hs project upload
hs project open  # Get installation URL

Key Configuration

The app requests these critical scopes (see src/app/app-hsmeta.json):

• sales-email-read - Email access (the key missing piece)
• crm.objects.contacts.read - Contact data
• crm.objects.companies.read - Company data
• crm.objects.deals.read - Sales pipeline data
• tickets - Support ticket history

Important: This is an account-level app (not user-level) to access sensitive data like emails.

OAuth Integration

1. Get Access Token

After app installation, exchange authorization code for tokens:

const response = await fetch('https://api.hubapi.com/oauth/v1/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    redirect_uri: 'http://localhost:3000/oauth-callback',
    code: 'AUTHORIZATION_CODE'
  })
});

2. Use Token for API Calls

const data = await fetch('https://api.hubapi.com/crm/v3/objects/emails', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

Common Gotchas

• Scope names: Use sales-email-read (not crm.objects.emails.read)
• User vs Account level: User-level apps can't access emails/tickets
• Redirect URLs: Must match exactly between app config and OAuth requests
• Token refresh: Access tokens expire ~30 minutes, implement refresh logic

Files Structure

src/app/
├── app-hsmeta.json              # Main OAuth configuration
└── settings/
    ├── new-settings-page-hsmeta.json
    ├── NewSettingsPage.tsx      # Optional settings UI
    └── package.json

Resources

• HubSpot OAuth Docs
• Available Scopes
• CRM API Reference

---

Note: This app provides OAuth authentication only. Your integration layer handles the actual customer intelligence queries using the obtained tokens.