What is HubSpot?

HubSpot is a CRM platform that combines marketing, sales, customer service, and content management tools. With over 194,000 customers, it's the go-to platform for businesses that want their sales and marketing teams to actually talk to each other. If you're building integrations, you need API access to sync data between HubSpot and your other systems.

What You Can Build with HubSpot APIs

HubSpot's APIs give you programmatic access to:

• Contact & Company Management: Sync customer data, update properties, manage associations between records
• Deal Pipeline Automation: Create deals, move them through stages, track revenue programmatically
• Marketing Automation: Trigger workflows, manage lists, track email engagement
• Custom Objects: Define and manage business-specific data structures beyond standard CRM objects
• Content Operations: Manage blog posts, landing pages, and website content through the CMS API

Getting Your HubSpot API Keys: Two Methods

Method 1: Private App (Recommended for Internal Integrations)

Private apps are perfect for internal tools and backend integrations. They use a single API key that never expires.

Step 1: Create a Private App

1. Log into your HubSpot account
2. Navigate to Settings → Integrations → Private Apps
3. Click Create a private app
4. Name your app (e.g., "Internal Data Sync")
5. Add a description so your team knows what this is for

Step 2: Configure Scopes

1. Go to the Scopes tab
2. Select only the permissions you need:
   • CRM: crm.objects.contacts.read, crm.objects.contacts.write
   • Marketing: content, forms, automation
   • Sales: crm.objects.deals.read, crm.objects.deals.write
   • Analytics: analytics.behavioral_events.send
3. Remember: Less is more. Don't request scopes you won't use

Step 3: Generate Your Access Token

1. Click Create app
2. Review the scopes one more time
3. Click Continue creating
4. Copy your access token immediately - you can't see it again
5. Store it securely (environment variables, not in code)

Step 4: Test Your Connection

curl https://api.hubapi.com/crm/v3/objects/contacts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If you get a JSON response with contacts data, you're connected.

Method 2: OAuth App (Required for Multi-Customer Integrations)

If you're building an app that multiple HubSpot customers will use, you need OAuth. This is where the OAuth dance nobody warns you about comes in.

Step 1: Create an OAuth App

1. Go to your HubSpot App Developer Account
2. Click Create app
3. Fill in:
   • App name: Your product name
   • App description: What your integration does
   • App logo: Your company logo (256x256px minimum)
4. Save your app

Step 2: Configure OAuth Settings

1. Navigate to Auth tab
2. Add redirect URLs:
   • Development: http://localhost:3000/auth/callback
   • Production: https://yourapp.com/auth/callback
3. Select required scopes (same as private app scopes)
4. Copy your:
   • Client ID
   • Client Secret
   • App ID

Step 3: Implement OAuth Flow

1. Authorization: Send users to:

https://app.hubspot.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=contacts%20forms

2. Token Exchange: When they return with a code:

curl -X POST https://api.hubapi.com/oauth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "code=RECEIVED_CODE"

3. Token Refresh: HubSpot tokens expire after 6 hours:

curl -X POST https://api.hubapi.com/oauth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Common Pitfalls

• Rate Limits: 100 requests per 10 seconds for OAuth apps, 500 for private apps
• Burst Limits: Daily limits vary by subscription tier (Free: 500K, Starter: 1M, Professional+: 10M)
• Scope Creep: Adding new scopes requires users to reauthorize
• Token Storage: Never store tokens in frontend code or git repositories
• API Versioning: v3 is current, but some endpoints still require v1 or v2

Managing HubSpot API Connectivity with Apideck's Vault

If you're integrating HubSpot alongside other CRM systems, handling OAuth flows and token refresh for each platform becomes a maintenance nightmare. Apideck's Vault eliminates this complexity:

• Secure credential storage with automatic token refresh - No custom OAuth implementation or token refresh logic needed
• Pre-built authentication UI - Embedded components handle the entire OAuth flow without building authorization pages
• Centralized connection monitoring - Monitor all CRM connections, validate credentials, and debug issues from one dashboard

Here's how to connect HubSpot through Apideck:

1. Access your Apideck dashboard and select Connections
2. Choose HubSpot from the CRM connectors
3. For OAuth setup, you'll need:
   • Client ID
   • Client Secret
   • Scopes required for your use case
4. Save configuration and click "Test Connection"
5. Users can then authorize through Vault's embedded UI

Once connected, you can access HubSpot data through Apideck's unified CRM API, which means the same code works for HubSpot, Salesforce, Pipedrive, and 50+ other CRMs.

Choosing Between Private Apps and OAuth

Use Private Apps when:

• Building internal tools or automation
• Single HubSpot account integration
• Backend processes without user interaction
• You need maximum API rate limits

Use OAuth when:

• Building a product for multiple HubSpot customers
• Need user-specific permissions
• Publishing to HubSpot's App Marketplace
• Compliance requires user consent flow

Advanced Considerations

Webhook Subscriptions

If you need real-time updates, set up webhooks:

1. Create a HubSpot app (OAuth only)
2. Configure webhook URLs in app settings
3. Subscribe to specific event types
4. Validate webhook signatures for security

Custom Objects API

For complex data models:

1. Define schemas via API or UI
2. Use the same authentication methods
3. Access through /crm/v3/objects/{objectType}
4. Remember: Custom objects count toward your object limits

Batch Operations

For bulk data operations:

• Use batch endpoints (/crm/v3/objects/contacts/batch/read)
• Maximum 100 records per batch request
• Implement exponential backoff for rate limit handling

Testing Your Integration

Before going live:

1. Use HubSpot's Test Account: Create a free developer test account
2. Monitor Rate Limits: Check response headers for X-HubSpot-RateLimit-*
3. Error Handling: Implement retry logic for 429 (rate limit) and 502/503 (temporary failures)
4. Logging: Track API calls, response times, and error rates

Next Steps

With your API keys configured:

1. Explore HubSpot's API documentation for endpoint details
2. Implement proper error handling and rate limit management
3. Set up monitoring for token expiration and API health
4. Consider using a unified API if you need multi-CRM support

For production deployments connecting multiple CRM systems, platforms like Apideck handle the authentication complexity, letting you focus on building features instead of maintaining OAuth implementations.

Conclusion

Getting HubSpot API keys is straightforward - pick private apps for internal use or OAuth for customer-facing integrations. The real work comes in handling rate limits, token refresh, and error scenarios. Whether you build direct integrations or use a unified API platform, proper authentication setup is the foundation of reliable HubSpot connectivity. #blog