Struggling to get your app talking to HubSpot the right way? One of my go-to tricks for secure and seamless integration is understanding how HubSpot’s OAuth access tokens work. It’s like getting the VIP pass for your applications to interact with HubSpot data, but with all the right security checks in place.

Connecting applications and services is a big part of how businesses operate today. With HubSpot being a central hub for so many teams—from marketing to sales and customer service—making sure your custom tools or third-party apps can securely talk to it is super important. We’re not just talking about getting data from one place to another. we’re talking about doing it safely, efficiently, and in a way that protects sensitive customer information. HubSpot, recognizing the need for robust security, transitioned away from simple API keys. Back in November 2022, they officially retired API keys, pushing developers towards more secure alternatives like Private Apps and OAuth 2.0. This move wasn’t just about changing a technical detail. it was a big step towards enhancing data security and giving users more control over what applications can access their HubSpot accounts. Using OAuth 2.0 isn’t just a recommendation. it’s often a requirement, especially if you’re building a public app destined for the HubSpot App Marketplace. Over 70% of developers now recommend OAuth 2.0 for API authorization due to its strong access management capabilities, and it significantly reduces the risk of data breaches. In this guide, we’ll walk through what HubSpot OAuth access tokens are, why they’re crucial, how you can get them, use them, and keep your integrations running smoothly and securely.

Table of Contents

What is OAuth Anyway? And Why HubSpot Uses It

Let’s start with the basics. Imagine you want to give a friend access to your house. You wouldn’t hand them your only house key, right? You’d probably give them a temporary pass or a separate, limited-access key. OAuth Open Authorization works kind of like that for your digital data. Instead of giving an application your full HubSpot username and password which is like handing over your master key!, OAuth 2.0 lets you grant specific, limited access to your HubSpot account. It’s a secure way for an application to get authorization from a user to access their data on another service like HubSpot without ever seeing their login credentials.

HubSpot specifically supports the OAuth 2.0 Authorization Code grant type. This is a widely used and robust method for authentication, especially for public applications that users install into their HubSpot accounts. It offers a better security posture than older methods because it never exposes your sensitive login details to the application itself.

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.

Amazon.com: Check Amazon for Cracking the Code:
Latest Discussions & Reviews:

OAuth vs. Personal Access Token and API Keys

This is where things can sometimes get a little fuzzy. You might hear terms like “personal access token” or “API key” floating around. So, what’s the difference, especially when talking about HubSpot?

API Keys Deprecated: As I mentioned, HubSpot has phased these out. The big problem with old API keys was that they were like master keys – if someone got hold of your API key, they pretty much had root access to everything in your HubSpot portal, with no restrictions. That’s a huge security risk!
Private Apps and Personal Access Tokens: HubSpot introduced Private Apps as a more secure alternative to API keys for single-account integrations. When you create a Private App, you get a unique access token sometimes referred to as a personal access token in other contexts, though HubSpot usually just calls it a Private App access token. The key difference here is that Private App tokens can be scoped to specific permissions. This means you can create a token that only allows reading contacts, for example, and nothing else. If that token is compromised, the damage is limited. You can also rotate or turn off a specific Private App token without affecting your whole portal. These are fantastic for internal tools or integrations you’re building just for your own HubSpot account.
OAuth for Public Apps and Multi-Account Integrations: This is where OAuth shines. If you’re building an app that other HubSpot users will install a “public app”, or if your app needs to work with multiple HubSpot accounts, OAuth 2.0 is the way to go. It’s designed for this kind of delegated access, where a user grants your app permission to act on their behalf without you ever touching their login credentials. Think of apps in the HubSpot App Marketplace – they all use OAuth.

So, while Private App tokens are a good step up from old API keys for specific internal needs, OAuth access tokens are the standard, secure, and recommended approach for public-facing applications or any integration that needs user consent to access multiple HubSpot accounts.

Understanding the Core Concepts of OAuth 2.0

Why HubSpot Uses OAuth 2.0

HubSpot didn’t just switch to OAuth for fun. there are some really solid reasons behind it:

Enhanced Security: This is the big one. With OAuth, your application never sees or stores a user’s HubSpot username and password. Instead, it gets an access token, which is a temporary credential that grants limited permissions. This drastically reduces the risk if your app’s database were ever compromised, as attackers wouldn’t get full login credentials.
Granular Permissions Scopes: OAuth allows for very specific control over what an application can do. You define “scopes” – essentially, a list of permissions your app needs e.g., crm.objects.contacts.read to read contacts, crm.objects.contacts.write to create them. When a user installs your app, they see exactly what permissions they’re granting. This transparency is key for user trust and security.
Delegated Access: Users can grant and revoke access for applications without changing their HubSpot password. This puts the user in control and makes managing third-party integrations much easier.
Scalability for Public Apps: If you’re building an app for the HubSpot App Marketplace, OAuth is a non-negotiable requirement. It provides a standardized and secure way for thousands of different HubSpot users to connect their accounts to your application.
Compliance: Modern security standards and regulations increasingly favor OAuth 2.0 for API authorization. Using it helps HubSpot and its developers meet these compliance requirements.

In short, OAuth 2.0 is the gold standard for secure, flexible, and scalable integrations, which is exactly what HubSpot needs given its role in so many businesses.

Getting Your Hands on a HubSpot OAuth Access Token: The Flow

How do you actually get one of these magical tokens? It involves a few steps, often called the Authorization Code flow, and it’s designed to be secure. Think of it as a handshake between your app, HubSpot, and the user.

Step 1: Setting Up Your HubSpot Developer App

Before you write a single line of code for the OAuth flow, you need to tell HubSpot about your application. Odoo vs Zoho vs HubSpot: Picking the Best Business Platform for You

Get a Developer Account: First off, you’ll need a HubSpot developer account. If you don’t have one, you can sign up for free on the HubSpot Developers portal.
Create an App: Once logged in, go to the “Apps” section and click “Create App.” Give your app a name and a description. This app acts as the container for your integration settings.
Configure Auth Settings: This is the most crucial part. Head over to the “Auth” tab for your new app. Here you’ll find and set some critical pieces of information:
- Client ID: This is a unique identifier for your application. HubSpot generates this for you.
- Client Secret: This is like a password for your application. Keep this secret! Never expose it in your frontend code or public repositories. HubSpot will provide this, and you’ll use it in server-side requests.
- Redirect URI Callback URL: This is the URL where HubSpot will send the user back after they’ve granted or denied your app permission. It’s super important this URL is exact and correctly configured in your HubSpot app settings. For security, in production, this must be an HTTPS URL. For local development, http://localhost might be acceptable.
- Scopes: Remember those granular permissions? This is where you define them. You select the specific HubSpot API endpoints and data your app needs access to e.g., crm.objects.contacts.read, crm.objects.contacts.write. Only ask for what you absolutely need – it’s good practice and enhances security. Make sure to also include the offline scope if you need a refresh token to maintain access when the user isn’t actively interacting with your app.

Step 2: Directing the User to HubSpot for Authorization

This is the part where the user interacts directly with HubSpot.
Your application will open a browser window or redirect the user to a special HubSpot authorization URL. This URL includes your client_id, your redirect_uri, and the scope of permissions your app is requesting.

Example of an authorization URL structure:
https://app.hubspot.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=SCOPES

When the user visits this URL, they’ll be prompted to log into their HubSpot account if they aren’t already and then presented with a consent screen. This screen lists your app’s name and the permissions scopes it’s asking for. The user then chooses which HubSpot account to grant access to and clicks “Connect app” or “Grant access.”

Step 3: Handling the Redirect and Authorization Code

After the user grants permission, HubSpot redirects them back to the redirect_uri you configured earlier. The magic here is that HubSpot appends a temporary authorization code as a query parameter to that URL.

It’ll look something like: https://your-redirect-uri.com/callback?code=YOUR_AUTHORIZATION_CODE HubSpot Outlook Plugin Greyed Out: Your Ultimate Troubleshooting Guide

This authorization code is short-lived, usually only valid for a few minutes. You need to capture this code from the URL on your server-side application.

Step 4: Exchanging the Authorization Code for Access and Refresh Tokens

This is the final hurdle to getting your tokens. Your server-side application takes that temporary authorization_code and exchanges it with HubSpot for the actual access token and refresh token. This is a direct, server-to-server POST request to HubSpot’s token endpoint.

You’ll send a POST request to https://api.hubapi.com/oauth/v1/token with the following parameters, typically as application/x-www-form-urlencoded:

grant_type: Should be authorization_code
client_id: Your app’s Client ID
client_secret: Your app’s Client Secret again, never expose this client-side!
redirect_uri: The exact same redirect URI used in Step 2
code: The authorization_code you received in Step 3

If everything goes well, HubSpot will respond with a JSON object containing:

access_token: This is your golden ticket! Use this to make API calls.
refresh_token: This is crucial for getting new access tokens when the current one expires.
expires_in: The lifetime of the access token in seconds typically 30 minutes, or 1800 seconds.
token_type: Usually “Bearer.”

Important: Store both the access_token and refresh_token securely in your backend system, along with the expires_in value and the timestamp when you received it. Mastering HubSpot Forms with NPM: Your Ultimate Guide to Seamless Integration

Using Your HubSpot Access Token

Now that you have an access_token, your application can finally start talking to HubSpot’s APIs!

How to Include It in API Requests

When your app makes a call to any HubSpot API endpoint, you need to include the access_token in the request header. It’s sent as a Bearer token in the Authorization header.

Here’s what that looks like in a curl example:

curl --request GET \
  --url "https://api.hubapi.com/crm/v3/objects/contacts?limit=10" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Replace YOUR_ACCESS_TOKEN with the actual token you received. HubSpot’s servers will then validate this token, check its associated scopes, and determine if your app has permission to perform the requested action. Master Your Inbox: How to Use the Outlook HubSpot Plugin for Smarter Sales

Scopes: What They Are and Why They Matter

Scopes are your app’s permissions. They define exactly what resources and actions your application is authorized to access within a user’s HubSpot account.

Minimizing Scope: A crucial security best practice is to always request the minimum necessary scopes. For example, if your app only needs to read contact information, don’t request crm.objects.contacts.write. This principle of “least privilege” limits the potential damage if your token is ever compromised.
User Consent: When a user authorizes your app, they’re explicitly agreeing to the requested scopes. Providing clear information about what your app needs to do helps build trust.
API Endpoint Access: Different HubSpot API endpoints require different scopes. The HubSpot API documentation clearly lists the required scopes for each endpoint. If your token doesn’t have the necessary scope, your API call will fail with an authorization error.
Scopes vs. User Permissions: It’s important to remember that an access token’s scopes reflect what the app is allowed to do, not necessarily what the user who authorized it can do. For example, if a user has permissions to only view contacts they own but grants your app crm.objects.contacts.read scope, your app might be able to view all contacts in the account. This is why careful scope selection is critical.

Managing Access Token Lifecycles

Access tokens aren’t forever. They’re designed to be short-lived for security reasons. This is where refresh tokens come into play, ensuring your integration can continue working without constantly bothering the user for re-authorization.

Access Token Expiration

HubSpot access tokens typically expire after 30 minutes 1800 seconds. You’ll see this expires_in value when you first exchange the authorization code for tokens. Using an expired access token will result in an OAuth token used to make this call expired error.

This short lifespan is a good security measure. If an access token were stolen, an attacker would only have a limited window to use it. However, it also means your application needs a strategy to get new access tokens automatically. Integrating HubSpot Tracking in Your Project: What’s the Deal with npm?

The Importance of Refresh Tokens

This is where the refresh_token becomes your best friend. Unlike access tokens, HubSpot refresh tokens generally do not expire. The only time a refresh token becomes invalid is if the user uninstalls your app from their HubSpot account, which explicitly revokes its access.

When your access_token is about to expire or has just expired, your application should use the refresh_token to request a new access_token and a new refresh_token from HubSpot. This process happens server-to-server, so the user doesn’t need to re-authenticate.

To refresh an access token, you’ll send another POST request to https://api.hubapi.com/oauth/v1/token, but with a different grant_type:

grant_type: Should be refresh_token
client_secret: Your app’s Client Secret
refresh_token: The refresh_token you previously received

HubSpot will respond with a new access_token, a new refresh_token it’s a good practice to always use the latest one, and a new expires_in value. You should immediately update your stored tokens with these new values.

A common practice: Before making an API call, your application should check if the current access_token is still valid by comparing its expiry time with the current time. If it’s expired or close to expiring, trigger the refresh token flow to get a new one before making the API call. This proactive approach prevents errors and ensures uninterrupted access. Understanding HubSpot Notifications: Your Business’s Digital Lifeline

When to Get a New Authorization Code

While refresh tokens are great for continuous access, there are a few scenarios where you might need to go through the full authorization code flow again:

Refresh Token Revoked/Expired: If the user uninstalls your app, the refresh token is immediately revoked. Also, if you lose the refresh token e.g., due to a data loss event and don’t have a valid one, you’ll need to re-initiate the full flow.
Changing Scopes: If your application needs to access new types of data or perform new actions that weren’t included in the original scopes, you’ll need to send the user through the authorization flow again with the updated scopes. This ensures they consent to the new permissions.

Common Pitfalls and Troubleshooting

Working with OAuth can sometimes feel a bit like detective work. Here are some common issues and how to tackle them:

Token Expiry Issues: This is probably the most frequent problem. If you’re getting “OAuth token expired” errors, chances are you’re not properly managing the refresh token flow. Make sure you’re storing the refresh_token securely and using it to get a new access_token before each API call or when the current one is near expiration. Ensure you included the offline scope when initially authorizing, as it’s required for refresh tokens.
Incorrect Scopes: If you’re getting 403 Forbidden errors or the API call isn’t returning the data you expect, double-check your app’s configured scopes in the HubSpot developer portal and the scopes included in your initial authorization request. Make sure they match what the API endpoint requires.
Redirect URI Mismatch: This is a classic. If HubSpot isn’t redirecting the user back to your app correctly, or you’re getting an Invalid redirect URI error, verify that the redirect_uri you’re sending in your authorization URL is exactly the same as what’s configured in your HubSpot app settings. Even a small / at the end can make a difference. Remember, in production, it needs to be HTTPS.
Client ID/Secret Issues: Ensure your client_id and client_secret are correct and haven’t been swapped or mistyped. These are sensitive credentials.
Server-Side Security: Never, ever embed your client_secret in client-side code like JavaScript in a browser. It must always be handled on your secure backend.
User Permissions: Remember that an app’s scopes don’t override a user’s in-HubSpot permissions. If the user who installed the app doesn’t have access to certain data in their HubSpot account, your app might not either, even if the token has the correct scope. This is less common but worth keeping in mind for complex scenarios.
Hub ID Mismatch: When a user grants access, they select a specific HubSpot portal Hub ID. Ensure your application is making API calls to the correct portal associated with the token.

HubSpot OAuth API and Tools

HubSpot provides excellent resources to help developers: What Exactly Are Non-Marketing Contacts in HubSpot?

HubSpot API Documentation: The official HubSpot developer documentation is your best friend. It has detailed guides on OAuth, specific API endpoints, required scopes, and example code.
Quickstart Apps: HubSpot offers a Node.js quickstart app that demonstrates the full OAuth 2.0 flow. If you’re new to this, using a sample app can be a great way to see how all the pieces fit together.
Postman: Tools like Postman are invaluable for testing API calls and debugging your OAuth flow. You can use Postman to simulate the authorization and token exchange requests, inspect responses, and test API calls with your access tokens. There are even HubSpot Postman collections available to help you get started.

Security Best Practices for OAuth Tokens

Security should always be top of mind when dealing with API integrations and sensitive data. Here are some best practices for managing your HubSpot OAuth tokens:

Never Expose Client Secret: This bears repeating: your client_secret should never be exposed in client-side code, public repositories, or logs. Treat it like a password for your application and store it securely on your server, ideally using environment variables or a dedicated secrets manager.
Secure Token Storage: Store access_tokens and refresh_tokens in a secure, encrypted database on your backend. Don’t store them in plain text. Implement strong access controls for this database.
Minimize Scope: Only request the absolute minimum permissions scopes your application needs to function. This adheres to the principle of “least privilege” and reduces the impact if a token is ever compromised.
Validate Redirect URIs: Always ensure your redirect_uri is strictly validated and matches what’s configured in your HubSpot app. A misconfigured redirect URI can be a major security vulnerability.
Error Handling: Implement robust error handling for your OAuth flow and API calls. Clear error messages can help you troubleshoot, but avoid leaking sensitive information in error responses. If an access token or refresh token is invalid, handle it gracefully by attempting a refresh or re-initiating the authorization flow if necessary.
Regular Audits: Periodically review your app’s permissions and connected integrations in HubSpot. Remove any apps or tokens that are no longer in use. Regular security audits can help catch misconfigurations.
Monitor for Suspicious Activity: Keep an eye on your application’s logs for unusual activity, such as a high volume of failed API requests or attempts to use revoked tokens.

By following these best practices, you can ensure your HubSpot integrations are not only functional but also secure, protecting your data and your users’ trust.

Frequently Asked Questions

What is a HubSpot OAuth access token?

A HubSpot OAuth access token is a temporary, secure credential that allows your application to access specific data and functionalities within a user’s HubSpot account on their behalf. It’s obtained through the OAuth 2.0 authorization flow, rather than direct username and password access, enhancing security.

What Exactly Are “Non-HubSpot Forms”?

How long does a HubSpot access token last?

HubSpot access tokens are short-lived, typically expiring after 30 minutes 1800 seconds. Because they expire quickly, you need to use a refresh token to get a new access token for continuous access without re-authenticating the user.

Do HubSpot refresh tokens expire?

Generally, HubSpot refresh tokens do not expire on their own. They remain valid indefinitely, allowing your application to obtain new access tokens. The only primary scenario where a refresh token becomes invalid is if the user uninstalls your app from their HubSpot account, which explicitly revokes the token. Also, make sure to include the offline scope when initially getting the authorization code, as it’s required for receiving a refresh token.

What is the difference between a HubSpot OAuth access token and a personal access token or API key?

The main difference lies in their purpose and security model. Old API keys offered broad, un-scoped access and are now deprecated due to security risks. Personal access tokens often associated with HubSpot Private Apps are scoped tokens for a single HubSpot account, useful for internal integrations. OAuth access tokens are specifically designed for public applications or integrations needing to access multiple HubSpot accounts with user consent, providing a higher level of security by separating app access from user credentials and allowing users to grant/revoke specific permissions scopes.

How do I get a new HubSpot access token once the old one expires?

When your access token expires, you use your refresh token to get a new one. Your application makes a server-to-server POST request to HubSpot’s token endpoint https://api.hubapi.com/oauth/v1/token with the grant_type set to refresh_token, along with your client_id, client_secret, and the refresh_token. HubSpot will then issue a new access token and a new refresh token. You should always use the latest refresh token you receive. Crafting Stellar Newsletters with HubSpot Templates: Your Ultimate Guide

What are “scopes” in HubSpot OAuth and why are they important?

Scopes define the specific permissions your application is requesting to access data and functionalities within a user’s HubSpot account. For example, crm.objects.contacts.read allows your app to read contact data. Scopes are crucial because they enforce the principle of “least privilege” – your app only gets access to what it absolutely needs. This minimizes security risks and provides transparency to users about the data their consenting to share.

Can I use HubSpot OAuth for private apps only used by my company?

Yes, you can use OAuth for private apps. However, for integrations that are only for your single HubSpot account, HubSpot’s Private Apps which use a unique access token configured with specific scopes are often simpler to set up and manage, as they don’t require the full OAuth redirect flow. OAuth becomes more necessary if your “private” app needs to be installed in multiple different HubSpot accounts or is intended for public distribution.

Partners

Cracking the Code: Everything You Need to Know About HubSpot OAuth Access Tokens