How to Connect HubSpot to n8n in (Complete Integration Guide)
Struggling with HubSpot API keys that suddenly stop working? You're not alone - HubSpot is phasing out traditional authentication methods. This guide shows you the modern way to connect HubSpot to n8n using OAuth 2.0 or app tokens, with troubleshooting tips for when things go wrong.
Why HubSpot Authentication Changed
If you've recently found your HubSpot API keys suddenly failing in n8n, you're experiencing HubSpot's ongoing security modernization. The company began phasing out traditional API keys in in favor of more secure OAuth 2.0 and app token authentication methods.
This shift catches many businesses off guard - workflows that ran perfectly for years suddenly break with cryptic permission errors. The change reflects HubSpot's commitment to enterprise-grade security, but creates immediate headaches for automation teams.
Key impact: By , all HubSpot portals will require OAuth 2.0 or app tokens for API access. Traditional API keys will completely stop working, breaking any existing n8n workflows still using them.
Step-by-Step Connection Guide
Connecting HubSpot to n8n takes just minutes when you use the right authentication method. Here's the foolproof process we use for all client implementations:
Step 1: Add HubSpot Node
In your n8n workspace, create a new workflow or open an existing one. Click "Add first step" or the "+" button between nodes, then search for "HubSpot" in the node picker. Select the official HubSpot node.
Step 2: Choose Authentication Method
In the node's credentials dropdown, click "Create new credential". You'll see three options: OAuth 2.0 (recommended), App Token, or API Key (legacy). For most users, OAuth 2.0 provides the best balance of security and convenience.
Step 3: Complete OAuth Flow
After selecting OAuth 2.0, click "Connect my account". A HubSpot window will open asking you to select the correct portal and approve permissions. If you have multiple HubSpot accounts, ensure you're authenticating with the right one.
Step 4: Name and Save Credential
Once authenticated, give your credential a descriptive name like "HubSpot Production" so you can easily identify it later. Verify the credential shows as "Connected" before proceeding.
Pro tip: At 2:15 in the video tutorial, we show how to handle two-factor authentication prompts that may appear during the OAuth flow if your HubSpot account has extra security enabled.
OAuth vs. App Tokens: Which to Choose
While OAuth 2.0 works for most use cases, HubSpot app tokens provide specific advantages in certain scenarios. Here's how to decide which authentication method fits your needs:
OAuth 2.0 is best when: You need quick setup without developer involvement, want automatic token refresh, or are working with standard HubSpot features. It authenticates as your user account with all your existing permissions.
App tokens shine when: You need granular permission control, are building system-to-system integrations, or require credentials that aren't tied to an individual user's account. They're ideal for production environments where you want to minimize permission creep.
The key difference comes down to accountability - OAuth actions are attributed to your user account in HubSpot's audit logs, while app token actions show the private app as the actor. Choose based on your compliance and reporting requirements.
Solving Common Connection Errors
Even with proper authentication, HubSpot-n8n connections can fail for several reasons. These are the most frequent issues we encounter and how to resolve them:
"Invalid OAuth access token" errors typically mean your token expired before n8n could refresh it. The solution is to reconnect your credential - the new token will have a fresh expiration date. Consider switching to app tokens if this happens frequently.
Permission denied errors indicate your OAuth scopes or app token permissions don't match what the workflow requires. Check the specific API endpoint being called against your credential's permissions. You may need to reconnect with expanded scopes.
Critical note: If you see "API key is no longer supported" errors, your HubSpot portal has completely disabled legacy authentication. You must switch to OAuth 2.0 or app tokens immediately - there's no workaround.
Security Best Practices
While HubSpot's modern authentication methods are secure by design, these additional measures will protect your data and prevent unauthorized access:
Credential naming: Always give your n8n HubSpot credentials descriptive names indicating their purpose and environment (e.g., "HubSpot Production - Marketing Automation"). This prevents accidental misuse in workflows.
Permission minimization: When using app tokens, grant only the specific API permissions your workflow requires. HubSpot's developer portal lets you select individual CRUD operations for each object type.
Regular audits: Review connected apps in your HubSpot portal quarterly. Remove any unused or outdated n8n connections to reduce your attack surface.
Advanced Configurations
Once you've mastered basic HubSpot-n8n connections, these advanced techniques can unlock additional capabilities:
Multiple account management: Create separate credentials for different HubSpot portals (e.g., production vs. sandbox). Use n8n's credential sharing features to safely distribute access across your team.
Custom object integration: HubSpot Enterprise plans support custom objects. Configure your app token or OAuth scopes to include these, then use n8n's "Custom Object" resource type in the HubSpot node.
Webhook verification: When receiving HubSpot webhooks in n8n, implement signature verification using your client secret to ensure payloads haven't been tampered with in transit.
Watch the Full Tutorial
For visual learners, our video tutorial demonstrates the complete HubSpot-n8n connection process from start to finish, including how to handle two-factor authentication prompts (at 2:15) and troubleshoot common errors (at 4:30).
Key Takeaways
HubSpot's authentication changes represent a necessary evolution in API security, even if they cause short-term disruption. By migrating to OAuth 2.0 or app tokens now, you'll future-proof your n8n workflows while benefiting from enhanced security features.
In summary: 1) OAuth 2.0 is the simplest solution for most users, 2) App tokens offer granular control for production environments, and 3) Traditional API keys will stop working entirely - migrate now to avoid workflow disruptions.
Frequently Asked Questions
Common questions about HubSpot-n8n integration
n8n supports three authentication methods for HubSpot: OAuth 2.0 (recommended for most users), HubSpot app tokens (for private apps), and traditional API keys (being phased out).
OAuth 2.0 provides the best balance of security and convenience, automatically refreshing tokens without manual intervention. App tokens offer granular permissions control but require more setup in HubSpot's developer portal.
- OAuth 2.0: User-friendly, automatic token refresh
- App tokens: Granular permissions, system-to-system
- API keys: Legacy method, not recommended
Many HubSpot accounts are phasing out traditional API keys in favor of OAuth 2.0 or app tokens. If your API key stops working, it's likely because your HubSpot portal administrator has disabled legacy API key support.
The solution is to switch to OAuth 2.0 authentication (which takes about 2 minutes to set up) or create an app token in HubSpot's developer settings. These modern methods provide better security and are required for all HubSpot portals by .
- Primary cause: HubSpot disabling legacy API keys
- Solution: Migrate to OAuth 2.0 or app tokens
- Time required: 2-5 minutes to switch
The n8n HubSpot node supports all major CRM objects including contacts, companies, deals, tickets, products, and engagements. You can perform create, read, update, and delete operations on these objects.
The node also supports HubSpot marketing features like email subscriptions and workflows, plus custom object operations if you're on an Enterprise plan. Nearly every HubSpot API endpoint is available through the node's various resource and operation options.
- Core objects: Contacts, companies, deals, tickets
- Marketing features: Email, workflows, forms
- Enterprise only: Custom objects
Permission errors typically occur when the OAuth scopes or app token permissions don't match what your workflow requires. First, verify you selected the correct HubSpot account during authentication.
Then check that your credential has all necessary scopes - you may need to reconnect with expanded permissions. For app tokens, verify the token has all required permissions in HubSpot's developer settings. The specific error message usually indicates which permission is missing.
- First step: Verify correct HubSpot account
- Second step: Check credential scopes/permissions
- Final step: Reconnect with expanded access
Yes, n8n allows you to create multiple HubSpot credentials, each connecting to a different account. Simply create separate credentials in n8n with distinct names (like 'HubSpot Production' and 'HubSpot Sandbox').
When building workflows, select the appropriate credential for each HubSpot node. This is particularly useful for agencies managing multiple client accounts or businesses maintaining separate production and development environments. Each credential maintains its own authentication independently.
- Use case: Agencies with multiple clients
- Implementation: Create named credentials
- Benefit: Isolated authentication per account
The connection is highly secure when using OAuth 2.0 or app tokens. n8n never stores your HubSpot login credentials - it only stores encrypted access tokens with limited lifetimes.
OAuth tokens automatically refresh, eliminating the risk of long-lived API keys. For maximum security, use app tokens with minimal required permissions and rotate them periodically through HubSpot's developer portal. All communication occurs over encrypted HTTPS connections.
- No credentials stored: Only encrypted tokens
- Automatic refresh: OAuth tokens stay current
- Encrypted transport: All communication over HTTPS
OAuth 2.0 authentication is user-centric and ideal for most business users - it authenticates as your HubSpot user account with permissions matching your user role. App tokens are application-centric, providing granular permissions independent of user roles.
OAuth is simpler to set up (just click 'Connect'), while app tokens require creating a private app in HubSpot first. The key difference comes down to accountability - OAuth actions are attributed to your user account in HubSpot's audit logs, while app token actions show the private app as the actor.
- OAuth: User attribution, easy setup
- App tokens: App attribution, granular control
- Best for: OAuth=most users, Tokens=systems
GrowwStacks specializes in building custom HubSpot-n8n integrations tailored to your business processes. Our team can handle the technical setup including OAuth configuration, permission scoping, and error handling.
We'll design workflows that sync your CRM data with other systems, automate marketing sequences, and create custom dashboards - all with proper security and maintenance procedures. 90% of our HubSpot integrations are completed within 2 business days, with full documentation and support.
- Custom HubSpot automation workflows
- Multi-system integration design
- Free 30-minute consultation
Ready to Automate Your HubSpot Workflows?
Every day without automation costs you hours of manual data entry and missed opportunities. Our n8n experts can have your HubSpot integration built, tested, and running in under 48 hours.