Struggling to get your app talking to HubSpot the right way? Learning how to use HubSpot OAuth is a must for securely connecting your services and unlocking a ton of automation possibilities. You see, when you want to build an app that talks to HubSpot and potentially works for many different businesses, you can’t just throw around passwords or old-school API keys anymore. HubSpot actually moved away from those less secure API keys back in 2022, and for good reason!

OAuth 2.0 is the modern, super secure way to let your application access a user’s HubSpot data without ever needing their login details. Think of it like a VIP pass: your app gets a special token that grants it specific access like reading contacts or creating deals, but it never sees the user’s main login credentials. This is crucial for protecting sensitive customer data and ensuring your integration plays by the rules.

In this guide, we’re going to break down the HubSpot OAuth example for public apps, focusing on the Authorization Code Grant flow. We’ll walk you through setting up your HubSpot developer account, creating your app, and then the step-by-step process of getting those all-important access and refresh tokens. We’ll even look at how to test this with tools like Postman and cover some essential best practices for keeping your integrations secure and running smoothly. By the time we’re done, you’ll have a clear roadmap to building robust and secure HubSpot integrations, opening doors to hubspot workflow examples, hubspot form api example solutions, and so much more!

Before we jump into the nitty-gritty, let’s get cozy with some key players in the OAuth world. It’s like understanding the characters in a play – once you know who’s who, the story makes a lot more sense. OAuth 2.0, which HubSpot wholeheartedly embraces, involves a few main components that work together to grant secure access:

• The Client Your App: This is your application, the one that wants to access HubSpot data on behalf of a user. It could be a website, a mobile app, or a server-side service.
• The Resource Server HubSpot API: This is where all the juicy HubSpot data lives. When your app wants to, say, fetch some contacts, it’s talking to the Resource Server.
• The Authorization Server HubSpot OAuth Server: This is the gatekeeper. It’s HubSpot’s system that handles the user authentication and issues the access tokens to your app.
• The Resource Owner HubSpot User: This is the actual HubSpot user who owns the data and decides whether to grant your app permission to access it.

Now, let’s talk about the special keys and passes involved:

0.0 0.0 out of 5 stars (based on 0 reviews) Excellent0% Very good0% Average0% Poor0% Terrible0% There are no reviews yet. Be the first one to write one. Your review Your overall rating Select a Rating5 Stars4 Stars3 Stars2 Stars1 Star Title of your review Your review Your name Your email This review is based on my own experience and is my genuine opinion. ​ Submit Review

Amazon.com: Check Amazon for Understanding the Core Latest Discussions & Reviews:

• Client ID: Think of this as your app’s public name tag. It’s a unique identifier that HubSpot assigns to your application when you create it.
• Client Secret: This is your app’s super-secret password. It’s a confidential string that only your application and HubSpot should know. Keep this secure, seriously!
• Redirect URI or Callback URL: This is where HubSpot sends the user back after they’ve given consent or denied it. It’s a specific URL in your application that’s registered with HubSpot.
• Scopes: These are the permissions your app is asking for. Instead of full access, you specify exactly what data and actions your app needs, like crm.objects.contacts.read to read contacts or crm.objects.companies.write to create companies. This concept of “least privilege” is a best practice in security.
• Authorization Code: This is a temporary, single-use code that HubSpot sends to your redirect_uri after a user grants permission. Your app then exchanges this code for actual tokens.
• Access Token: This is the main “entry ticket” for your app to make API calls to HubSpot. It’s usually short-lived often around 30 minutes and needs to be kept confidential.
• Refresh Token: This is your “VIP ticket” to get new access tokens when the old one expires. It’s much longer-lived and allows your app to maintain offline access to HubSpot data without requiring the user to re-authorize every time. You definitely need to store this securely.

Step-by-Step: Setting Up Your HubSpot OAuth App

Alright, let’s get your hands dirty and set up your HubSpot app. This is the foundation for any successful OAuth integration.

Prerequisites: Get Your Developer Account Ready

First things first, you’ll need a HubSpot Developer Account. If you don’t have one, just head over to the HubSpot Developers portal and sign up for a free account. Once you’re in, you’ll see a dashboard that lets you manage your apps and integrations.

Create Your App

Now, let’s create your public application. This is where you tell HubSpot about your awesome app.

1. Navigate to the Developer Dashboard: From your HubSpot Developer Account, click on “Apps” in the sidebar.
2. Create a New App: You’ll see an option to “Create app.” Go ahead and click that.
3. Basic Information:
   • App Name: Give your app a descriptive name, like “My Awesome HubSpot Connector.” This is what users will see when they’re asked to authorize your app.
   • Description: Briefly explain what your app does.
   • Optional App Logo: Upload a logo to make your app look professional.
4. Auth Settings: The Heart of OAuth
   • Once you’ve created the app, go to the “Auth” tab in your app settings. This is where you’ll find your crucial OAuth credentials.
   • Client ID: HubSpot will automatically generate this for you. Copy it down – you’ll need it soon.
   • Client Secret: This is also generated automatically. Treat this like a password. Never expose it in client-side code like in a web browser and keep it secure on your server.
   • Redirect URLs: This is super important. This is the URL or URLs on your server where HubSpot will send the user back after they’ve granted or denied permissions.
     • You must specify a valid HTTPS URL for production environments. For local development, you might use http://localhost:3000/oauth-callback or whatever port and path your local server uses.
     • Add your redirect_uri here. If you’re building for multiple environments dev, staging, production, you can add multiple.
     • Pro Tip: Misconfigured redirect URIs are a common source of integration headaches. Double-check this!
   • Scopes: Here’s where you define what your app can actually do in a user’s HubSpot account.
     • Click “Add new scopes” and select the permissions your application needs.
     • For example, if you want to create contacts and read company data, you’d select crm.objects.contacts.write and crm.objects.companies.read.
     • Always follow the principle of least privilege: Only request the scopes absolutely necessary for your app’s functionality. Requesting too many scopes can make users hesitant to authorize your app.
     • Make sure to include the oauth scope, especially for apps created before April 2024, as it’s required for the integration to work.

Once you’ve set all this up, you’ve got your app registered, your Client ID and Client Secret, and your Redirect URI and Scopes defined. You’re ready for the actual OAuth flow!

The HubSpot OAuth 2.0 Flow: A Detailed Walkthrough

The HubSpot OAuth 2.0 process follows a standard “Authorization Code Grant” flow, which is super common and secure for web applications. Let’s break down each step. Odoo vs Zoho vs HubSpot: Picking the Best Business Platform for You

Step 1: Initiating the Authorization Request

This is where your application sends the user to HubSpot to ask for permission.

Imagine a user wants to connect their HubSpot account to your app. Your app needs to generate a special URL – the Authorization URL – and then redirect the user’s browser to it.

The Authorization URL will look something like this:

https://app.hubspot.com/oauth/authorize
?client_id={your_client_id}
&scope={url_encoded_scopes}
&redirect_uri={your_redirect_uri}
&state={optional_state_parameter} HubSpot Outlook Plugin Greyed Out: Your Ultimate Troubleshooting Guide

Let’s unpack those parameters:

• client_id: This is the Client ID you copied from your HubSpot app settings.
• scope: This is a space-separated list of all the scopes you need, URL-encoded. So, if you need crm.objects.contacts.read and crm.objects.contacts.write, it would look like crm.objects.contacts.read%20crm.objects.contacts.write.
• redirect_uri: This is the Redirect URL you set up in your app settings. It must exactly match one of the URLs configured in your HubSpot app.
• state Optional but Recommended: This is a parameter that your app generates and sends along with the authorization request. HubSpot will send it back to your redirect_uri untouched. You should use this to prevent Cross-Site Request Forgery CSRF attacks by verifying that the state parameter you get back matches the one you sent. Think of it as a secret handshake to ensure the callback is legitimate.

Example Authorization URL Construction Conceptual:

Let’s say in your server-side code e.g., Node.js, Python, PHP, you’d build this URL dynamically.

// Example in Node.js conceptual
const clientId = process.env.HUBSPOT_CLIENT_ID.
const redirectUri = process.env.HUBSPOT_REDIRECT_URI.
const scopes = "crm.objects.contacts.read crm.objects.contacts.write". // Space separated
const state = generateRandomString. // Implement this securely

const authorizationUrl = `https://app.hubspot.com/oauth/authorize?` +
  `client_id=${clientId}` +
  `&scope=${encodeURIComponentscopes}` +
  `&redirect_uri=${encodeURIComponentredirectUri}` +
  `&state=${state}`.

// Then, redirect the user's browser to this URL:
// res.redirectauthorizationUrl.

When the user clicks a “Connect to HubSpot” button in your app, they’ll be sent to this authorizationUrl.

Mastering HubSpot Forms with NPM: Your Ultimate Guide to Seamless Integration

Step 2: Handling the Callback and Getting the Authorization Code

After the user is redirected to HubSpot, they’ll see a consent screen where they can choose which HubSpot account to connect and review the permissions scopes your app is requesting.

If the user grants access, HubSpot will redirect their browser back to your redirect_uri. This callback URL will have two important query parameters appended to it:

• code: This is the authorization_code. It’s a temporary code that’s only valid for a short time usually minutes.
• state: This is the state parameter that your app sent in the initial request. You must verify this matches the state you sent to prevent CSRF.

Example Callback URL:

https://your-app.com/oauth-callback?code=ae2cc34...&state=your_secure_state_string

Your application’s /oauth-callback endpoint or whatever you named it needs to be ready to receive this request and extract these parameters. Master Your Inbox: How to Use the Outlook HubSpot Plugin for Smarter Sales

Step 3: Exchanging the Code for Tokens

This is where your app gets its valuable access_token and refresh_token.

Once your app has the authorization_code from the previous step, it needs to make a server-to-server POST request to HubSpot’s token endpoint /oauth/v1/token. This request is made directly from your server, not from the user’s browser, because it involves your Client Secret.

The request body needs to be application/x-www-form-urlencoded and contain these parameters:

• grant_type: This should be authorization_code for this initial exchange.
• client_id: Your app’s Client ID.
• client_secret: Your app’s Client Secret. Keep this secure!
• redirect_uri: The same redirect_uri you used in the initial authorization request.
• code: The authorization_code you just received from the callback.

Example POST Request Conceptual using fetch or curl: Integrating HubSpot Tracking in Your Project: What’s the Deal with npm?

const tokenUrl = “https://api.hubapi.com/oauth/v1/token“.
const payload = new URLSearchParams.
payload.append’grant_type’, ‘authorization_code’.
payload.append’client_id’, process.env.HUBSPOT_CLIENT_ID.
payload.append’client_secret’, process.env.HUBSPOT_CLIENT_SECRET.
payload.append’redirect_uri’, process.env.HUBSPOT_REDIRECT_URI.
payload.append’code’, receivedAuthCode.

fetchtokenUrl, {
method: ‘POST’,
headers: {
‘Content-Type’: ‘application/x-www-form-urlencoded’,
},
body: payload.toString,
}
.thenresponse => response.json
.thendata => {
const accessToken = data.access_token.
const refreshToken = data.refresh_token.
const expiresIn = data.expires_in. // e.g., 1800 seconds 30 minutes

// Store these securely!
console.log”Access Token:”, accessToken.
console.log”Refresh Token:”, refreshToken.
console.log”Expires In:”, expiresIn.
.catcherror => {
console.error”Error exchanging code for tokens:”, error.
}.

The response from HubSpot will be a JSON object containing:

• access_token: Your temporary access token.
• refresh_token: Your long-lived refresh token.
• expires_in: The lifetime of the access_token in seconds often 1800, or 30 minutes.
• token_type: Usually “Bearer”.
• scope: The actual scopes granted.

Crucial Step: You must securely store the access_token and, more importantly, the refresh_token in your database, associated with the HubSpot account that authorized your app. The refresh_token is essential for maintaining continued access without user re-authorization. Understanding HubSpot Notifications: Your Business’s Digital Lifeline

Step 4: Using the Access Token for API Calls

With your shiny new access_token, your app can finally make authenticated requests to the HubSpot API!

To do this, you’ll include the access_token in the Authorization header of your HTTP requests, using the Bearer token type.

Example API Call Conceptual: Fetching contacts:

Let’s say you want to get a list of contacts using the crm.objects.contacts.read scope. What Exactly Are Non-Marketing Contacts in HubSpot?

const contactsApiUrl = “https://api.hubapi.com/crm/v3/objects/contacts“.
const accessToken = “YOUR_STORED_ACCESS_TOKEN”. // Retrieve from your secure storage

fetchcontactsApiUrl, {
method: ‘GET’,
‘Authorization’: Bearer ${accessToken}, // This is how you authenticate
‘Content-Type’: ‘application/json’,
console.log”HubSpot Contacts:”, data.results.
// You can now process this contact data in your app!
console.error”Error fetching contacts:”, error.

This is how your app interacts with HubSpot to, for example, build hubspot dashboard examples or pull data for hubspot email examples. Each API call needs that Authorization: Bearer <access_token> header.

Managing Tokens: Refreshing and Best Practices

Access tokens are intentionally short-lived for security reasons. They usually expire after about 30 minutes. If your app needs to continue interacting with HubSpot beyond this period which it almost certainly will, you’ll need to use the refresh_token to get a new access_token.

What Exactly Are “Non-HubSpot Forms”?

Access Token Expiration

When an access_token expires, any API requests you make with it will fail, typically with a 401 Unauthorized or similar error. Your app needs to be ready to handle this.

Refreshing the Access Token

This is where the refresh_token comes to the rescue. When you detect an expired access_token, your app should use the refresh_token to get a new one. This is another server-to-server POST request to the same token endpoint /oauth/v1/token.

The request body for refreshing a token looks slightly different:

• grant_type: This should be refresh_token.
• client_secret: Your app’s Client Secret.
• refresh_token: The refresh_token you previously stored.

Example POST Request for Refreshing Conceptual: Crafting Stellar Newsletters with HubSpot Templates: Your Ultimate Guide

payload.append’grant_type’, ‘refresh_token’.
payload.append’refresh_token’, storedRefreshToken. // The refresh token you have

const newAccessToken = data.access_token.
const newRefreshToken = data.refresh_token. // You might get a new refresh token too!
const expiresIn = data.expires_in.

// IMPORTANT: Update your stored tokens with the new ones!
console.log”New Access Token:”, newAccessToken.
console.log”New Refresh Token if provided:”, newRefreshToken.
console.log”New Expires In:”, expiresIn.
console.error”Error refreshing token:”, error.
// Handle scenarios where refresh token also fails e.g., user uninstalled app

HubSpot’s response will again include a new access_token and potentially a new refresh_token. It’s crucial to update your stored tokens with the new ones you receive. This ensures your app always has valid credentials.

Supercharge Your HubSpot with N8n: Your Ultimate Automation Sidekick

Security Considerations

Security is paramount when dealing with OAuth and sensitive user data.

• HTTPS Everywhere: Always use HTTPS for your redirect_uri and for all communication with HubSpot.
• Never Expose Client Secret: Your Client Secret should only be used on your server-side code. Never embed it in client-side JavaScript, mobile apps, or any publicly accessible code.
• Secure Storage of Tokens: Access tokens and refresh tokens must be stored securely. In a web application, this typically means storing them in an encrypted database on your server, associated with the HubSpot user. Avoid storing them in plain text, local storage, or cookies on the client side.
• Validate state Parameter: Always verify the state parameter in the callback to prevent CSRF attacks.
• Principle of Least Privilege for Scopes: As mentioned, only request the minimum necessary permissions.
• Error Handling: Implement robust error handling for all API calls and token exchanges. Be prepared for tokens to expire, invalid tokens, or other API errors.

Beyond the Basics: Advanced Tips and Use Cases

Choosing Scopes Wisely

Carefully consider the functionality of your app and request only the necessary scopes. HubSpot offers a wide range of scopes covering CRM objects contacts, companies, deals, marketing tools marketing.forms.read, CMS features cms.hubdb.tables.read, and more. If your app only needs to read contacts, don’t ask for permission to write contacts or read emails.

Optional Scopes

Sometimes your app might offer features that depend on a user’s HubSpot account tier. You can use optional_scope parameters in your authorization URL. If a user on a lower tier account doesn’t have access to a specific tool, HubSpot will automatically drop that optional scope from the authorization request. Your app needs to be able to check which scopes were actually granted and adjust its functionality accordingly.

Deleting Refresh Tokens

If a user uninstalls your app from their HubSpot account, you should delete the corresponding refresh_token from your storage. HubSpot provides an endpoint DELETE /oauth/v1/refresh-tokens/{token} to explicitly delete a refresh token, which is a good practice for cleanup. N8n HubSpot Scopes: Your Ultimate Guide to Powerful Automation

Real-World HubSpot Examples and Integrations

Understanding OAuth opens up a world of possibilities for integrating with HubSpot. Here are some hubspot examples of what you can build:

• Data Synchronization: Automatically sync contacts, companies, and deals between HubSpot and other CRMs or internal databases. This can be crucial for maintaining hubspot pipeline examples consistency across platforms.
• Custom Reporting: Pull data into custom hubspot dashboard examples or business intelligence tools for deeper analytics.
• Automated Workflows: Trigger hubspot workflow examples in HubSpot based on actions in your external application, or vice versa.
• Custom Forms and Landing Pages: Integrate custom forms, potentially using a hubspot form api example to create or update contacts based on submissions.
• Email Automation: Connect your app to send personalized hubspot email examples or manage hubspot newsletter examples based on user behavior tracked by your app.
• Ticketing Systems: Create or update HubSpot tickets based on support interactions from another platform.
• Website Personalization: Use HubSpot data to personalize content on your hubspot website examples.

HubSpot OAuth with Postman: A Practical Approach

Testing your OAuth flow can feel a bit daunting, but tools like Postman make it much easier. Postman is widely used by developers to test APIs, and it has excellent support for OAuth 2.0.

Here’s a simplified way to set up Postman for HubSpot OAuth postman: Supercharge Your Workflow: The Ultimate Guide to Notion HubSpot Integration

1. Create a New Request: In Postman, create a new HTTP request.
2. Go to the Authorization Tab: Select “OAuth 2.0” from the “Type” dropdown.
3. Configure “Get New Access Token”:
   • Token Name: Give it a name e.g., “HubSpot OAuth Token”.
   • Grant Type: Select “Authorization Code.”
   • Callback URL: This must be your redirect_uri that you configured in your HubSpot app settings. For testing, it might be http://localhost:3000/oauth-callback or a placeholder if Postman handles the callback directly.
   • Auth URL: https://app.hubspot.com/oauth/authorize
   • Access Token URL: https://api.hubapi.com/oauth/v1/token
   • Client ID: Your Client ID from HubSpot.
   • Client Secret: Your Client Secret from HubSpot.
   • Scope: The space-separated scopes e.g., crm.objects.contacts.read crm.objects.contacts.write.
   • State: A random string you generate optional but good practice.
   • Client Authentication: Select “Send client credentials in body.”
4. “Get New Access Token” Button: Click this button. Postman will open a browser window, take you to HubSpot’s authorization screen, and ask you to log in and grant permissions.
5. Authorize and Redirect: After you authorize, HubSpot will redirect back to your specified callback URL. Postman intercepts this, grabs the authorization_code, and automatically exchanges it for an access_token and refresh_token.
6. Use the Token: Postman will then let you use this token in subsequent API requests. You can even set up environments in Postman to manage your access_token and refresh_token as environment variables for easier testing and refreshing.
7. Testing Refresh Tokens: Postman also allows you to manually trigger a token refresh using the refresh_token you received, which is super handy for making sure that part of your flow works.

Using Postman for your HubSpot OAuth example is a great way to understand each step of the flow and troubleshoot any issues before you even write a single line of server-side code.

Frequently Asked Questions

What is HubSpot OAuth and why do I need it?

HubSpot OAuth is a secure authentication method that allows your application to access a user’s HubSpot data without them having to share their login credentials. Instead of passwords, it uses authorization tokens. You need it because HubSpot has deprecated API keys, and OAuth provides a much safer, more flexible, and scalable way to build integrations, especially for apps that will be used by multiple HubSpot accounts or listed on the App Marketplace.

How do I get my Client ID and Client Secret for HubSpot OAuth?

You get your Client ID and Client Secret by creating an app in your HubSpot Developer Account. Once the app is created, navigate to its “Auth” settings tab, and you’ll find both the Client ID and Client Secret displayed there. Remember to keep your Client Secret confidential.

What is a Redirect URI and why is it important?

The Redirect URI also known as Callback URL is a specific URL in your application where HubSpot redirects the user’s browser after they have granted or denied permission for your app to access their HubSpot account. It’s crucial because HubSpot only sends sensitive information like the authorization code to pre-registered and validated Redirect URIs, which is a key security measure. It must exactly match one of the URLs you configured in your HubSpot app settings.

What are “scopes” in HubSpot OAuth?

Scopes define the specific permissions your application is requesting from a HubSpot user. Instead of granting full access, scopes allow you to specify exactly what types of data your app can read, write, or modify e.g., crm.objects.contacts.read to read contacts, crm.objects.deals.write to create deals. Choosing the right scopes is important for security and user trust. Understanding Non-HubSpot Forms: Your Guide to Smarter Data Capture

How long do HubSpot access tokens last, and how do I get a new one?

HubSpot access tokens are typically short-lived, often expiring after 30 minutes 1800 seconds. When an access token expires, your application will receive an authentication error. To get a new one, you use the refresh_token that you received during the initial OAuth flow. Your application makes a server-to-server POST request to HubSpot’s token endpoint /oauth/v1/token with grant_type=refresh_token, your client_id, client_secret, and the refresh_token. HubSpot then issues a new access_token and sometimes a new refresh_token, which you should securely store and use.

Can I use HubSpot OAuth for private internal integrations, or only for public apps?

HubSpot recommends OAuth primarily for public apps designed to be installed by multiple HubSpot accounts or listed on the App Marketplace. For private, internal integrations that only need to access a single specific HubSpot account, HubSpot offers “Private App Tokens” sometimes called static auth access tokens, which can be simpler to set up. However, if you anticipate needing more flexibility or potential expansion, using OAuth even for internal tools can be a good long-term strategy.

Is it possible to test HubSpot OAuth with Postman?

Yes, absolutely! Postman is an excellent tool for testing the HubSpot OAuth flow. You can configure Postman’s OAuth 2.0 authorization settings with your Client ID, Client Secret, Auth URL, Access Token URL, Redirect URI, and scopes. Postman can then guide you through the authorization process, handle the redirect, and automatically exchange the authorization code for access and refresh tokens, making it very straightforward to test your integration step by step.

Harnessing the Power of NPS HubSpot: Your Ultimate Guide to Customer Loyalty