HubSpot API Credentials

Overview

HubSpot has had several authentication methods over the years. If you’ve been told to “get your API key” or “set up OAuth,” this guide explains the differences and which one you actually need.

Credential Types

Private App Tokens (Recommended)

This is what we use for most integrations. A private app token is:

• Tied to a specific app you create inside your HubSpot account
• Scoped — you control exactly what it can read and write
• Doesn’t expire automatically (though you can rotate it anytime)
• Simple to set up and manage

When to use: Almost always. If we ask you to create credentials, this is usually what we mean.

How to set it up: Follow our HubSpot Private App Setup guide.

OAuth 2.0

OAuth is a more complex authentication method where you authorize our application to access your HubSpot account through a browser-based flow. Instead of copying a token, you click a link, log in, and approve access.

When to use: When we’re building an integration that needs to act on behalf of a specific user, or when we’re connecting a multi-tenant application. We’ll tell you if OAuth is needed — you won’t need to configure it yourself.

How it works:

1. We send you an authorization link
2. You click it and log into HubSpot
3. You review the permissions and approve
4. HubSpot sends us a token behind the scenes
5. We handle token refreshes automatically

Legacy API Keys (Deprecated)

HubSpot used to offer a single API key per account. These were deprecated in late 2022 and fully sunset in 2023. If you have an old integration using an API key, it no longer works.

If you see references to an “API key” in old documentation or from other vendors, point them to private apps instead. The API key approach has been replaced entirely.

Finding Your Hub ID

Your Hub ID is the numeric identifier for your HubSpot account. You’ll need it occasionally when setting up integrations.

1. Log into HubSpot
2. Look at the URL in your browser — it will contain a number like app.hubspot.com/contacts/12345678. That number is your Hub ID.
3. You can also find it by clicking your account name in the top right corner of HubSpot. The Hub ID is displayed below the account name.

Checking Active Scopes

If you already have a private app and want to verify what it can access:

1. Go to Settings, then Integrations, then Private Apps
2. Click on the app name
3. Select the Scopes tab
4. You’ll see a list of all permissions currently granted

If we request access to something not on the list, you can add scopes by editing the app. The token stays the same — no need to generate a new one.

Common Issues

“I Can’t Find Private Apps”

You need Super Admin access. Check Settings, then Users & Teams to see your role. If you’re not a Super Admin, ask someone who is to either create the app or upgrade your permissions.

“I Have an Old API Key”

It no longer works. Create a private app instead. The setup takes about 10 minutes and the private app approach is more secure since you control exactly what it can access.

“Multiple HubSpot Accounts”

If your organization has separate HubSpot accounts (common with sandbox or testing environments), make sure credentials come from the correct account. We’ll specify which one — usually production, but sometimes we start in sandbox for testing.

Next Steps

• Need to create a private app? Follow the step-by-step setup guide
• Starting a new project? Complete the onboarding checklist
• Learn more about our HubSpot Implementation Services