Updated June 18, 2026 by Sunny Chauhan.

The single most common question I get from founders shipping their first HubSpot integration: "Do I use an API key or OAuth?" The answer is "neither, you probably want a Private App access token unless you're building a Marketplace app, in which case you want OAuth." HubSpot has three authentication mechanisms, one of which (the legacy API key) was deprecated in November 2022 and quietly removed for new accounts in 2024. For most builders in 2026, the choice is Private App access tokens (for internal integrations) or OAuth access tokens (for Marketplace apps). Here's how to pick, how to store them, and what the May 2026 certification review now asks about token handling.

Pro Tip

TL;DR HubSpot has three API authentication mechanisms: 1/ Legacy API keys (deprecated, do not use), 2/ Private App access tokens (long-lived, scoped, one per app per portal, for internal integrations), and 3/ OAuth access tokens (short-lived, refreshable, one per portal install, required for Marketplace apps). For Marketplace certification, use OAuth. The May 2026 security questionnaire asks how you store, refresh, and rotate tokens. Encrypt at rest, never log them, refresh before expiry, and have a clear revocation path on uninstall.

HubSpot's authentication story has consolidated over the last three years. Here's the current state:

These are the old account-scoped API keys that HubSpot phased out starting November 2022. They were a single string per account that granted full read/write access to everything. Convenient and dangerous in equal measure.

In 2026, you cannot generate new legacy API keys. Existing ones still work in some accounts but HubSpot has been migrating customers off them. Any new development against a HubSpot account should not use this mechanism. If your codebase still uses legacy keys, migrate.

A Private App is a HubSpot-account-scoped integration that lives in one portal. You configure it from a customer's HubSpot settings (Integrations → Private Apps). It generates a single access token. The token is long-lived (doesn't expire on its own), scoped to specific permissions you choose at creation, and only works against the portal that created it.

Best for: → Internal integrations (your company connecting your own HubSpot to your own internal tools) → Single-customer integrations where the customer creates the Private App themselves → One-off ETL or data-sync jobs

Not allowed for: → Marketplace listings. Apps you intend to distribute through the Marketplace must use OAuth, not Private App tokens.

OAuth is the standard public-app authentication. The customer installs your app from the Marketplace (or via a direct OAuth install link), approves the scopes, and your server gets:

→ An access token (short-lived, typically 6 hours) → A refresh token (long-lived, used to mint new access tokens) → The portal id (which customer's HubSpot this token belongs to)

This is the only mechanism for Marketplace apps. It's also the right choice for any multi-tenant integration where multiple customers install your app independently.

Three quick decision rules:

→ Are you building a Marketplace app? OAuth. No exceptions.

→ Are you connecting your own HubSpot to your own infra (one portal, one integration)? Private App.

→ Are you connecting multiple customer HubSpots to your SaaS product? OAuth. Private Apps don't scale to multi-tenant because each customer would have to create their own Private App and paste the token into your product. Bad UX, bad security.

The clean way to think about it: Private Apps are for the customer connecting their portal to their own tooling. OAuth is for a vendor (you) connecting many portals to your product.

The May 2026 HubSpot certification security questionnaire (HubSpot Marketplace Certification Requirements) introduced explicit questions about token handling. The relevant ones, paraphrased:

1/ How are tokens encrypted at rest? 2/ How are tokens transmitted between services in your infra? 3/ Who in your organization has access to production tokens? 4/ What is your token rotation policy? 5/ What happens to tokens on app uninstall?

The patterns reviewers expect:

→ Encrypted at rest. Tokens are stored in a database with field-level encryption, or in a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault). Plain-text storage in a database column will get flagged.

→ TLS everywhere. Tokens transit your services over TLS only. No internal HTTP that carries tokens unencrypted.

→ Least-privilege access. Only the services that need tokens have decrypt permissions. Engineers don't have routine access to production tokens; access is via break-glass with audit logging.

→ Refresh before expiry. Refresh tokens proactively (e.g., 30 minutes before the 6-hour access token expires). Don't wait for a 401, refresh on a schedule and on detected 401s as a backstop.

→ Revoke on uninstall. When the customer uninstalls your app, HubSpot calls your uninstall endpoint. Delete the tokens immediately. Don't leave them in cold storage.

Once you have an access token and refresh token, the refresh flow is straightforward:

```javascript async function refreshHubSpotToken(refreshToken, clientId, clientSecret) { const response = await fetch('https://api.hubapi.com/oauth/v1/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'refresh_token', client_id: clientId, client_secret: clientSecret, refresh_token: refreshToken }) });

if (!response.ok) { throw new Error(Token refresh failed: ${response.status}); }

const data = await response.json(); return { accessToken: data.access_token, refreshToken: data.refresh_token, expiresIn: data.expires_in }; } ```

Three things worth flagging:

1/ The refresh token may rotate. HubSpot might return a new refresh token in the response. Always persist whatever you get back, don't assume the old refresh token still works.

2/ Refresh tokens can be revoked. If the customer reinstalls your app, the old refresh token becomes invalid. Your code should handle a 400 from the refresh endpoint gracefully (treat it as "customer disconnected, mark integration as needing reauth").

3/ The client secret is sensitive. The client secret is global to your app (not per-portal). Treat it like a database password. Store it in a secrets manager. Don't ship it in client-side code or commit it to version control.

A common architectural mistake: storing OAuth tokens in a single shared table without proper isolation. When you have 50 customer portals installed, you have 50 sets of tokens, and your code must be careful to always use the right token for the right portal.

The pattern that works:

→ Index tokens by portalId (the HubSpot account id) → Every API call carries the portalId context up from the request → The token-fetching code looks up by portalId; if expired, refreshes; returns the access token

That last layer (fetch-or-refresh) becomes a single function in your codebase. Every other service uses it. Centralization here means you can change the storage backend without rewriting fifteen callers.

For Salesforce ISVs, the analogy is: → HubSpot Private App ≈ Salesforce Connected App with Username-Password OAuth flow (single org, internal) → HubSpot OAuth ≈ Salesforce Connected App with Web Server OAuth flow (multi-tenant, customer-installable)

The threat model is the same. Token theft = full account compromise. The protections are the same. Encryption at rest, TLS in flight, least-privilege access, clear revocation on uninstall.

At Appnigma we ship Salesforce 2GP Managed Packages where the package itself runs in the customer's org (no token needed because Apex executes server-side in their context). For HubSpot, the analogous architectural shift is using App Cards (UI extensions that render in HubSpot's UI without needing tokens for read access). Where you can avoid carrying tokens, do.

• [ ] Using OAuth (not Private App, not legacy API key) → Yes / No

• [ ] Tokens encrypted at rest (field-level encryption or secrets manager) → Yes / No

• [ ] TLS for all token-carrying traffic → Yes / No

• [ ] Refresh tokens persisted correctly (handle rotation in response) → Yes / No

• [ ] Refresh-before-expiry implemented (don't wait for 401) → Yes / No

• [ ] 400 from refresh endpoint handled (mark integration as disconnected) → Yes / No

• [ ] Uninstall endpoint deletes tokens immediately → Yes / No

• [ ] Client secret stored in secrets manager (not in code or env file in repo) → Yes / No

• [ ] Audit logging on access to production tokens → Yes / No

• [ ] Documented token rotation policy → Yes / No

A revenue intelligence product (analogous to Avoma or Gong) was submitting their HubSpot Marketplace listing in June 2026 and hit the new security questionnaire for the first time. Their initial setup: tokens stored in a Postgres column, encrypted at the disk level only (not field-level), accessed by every microservice in their backend.

The reviewer flagged three things: 1/ Field-level encryption was missing 2/ Token access wasn't scoped (any service could read any portal's tokens) 3/ Uninstall flow didn't immediately delete tokens (relied on a nightly cleanup job)

Fix took 3 days. They moved tokens to AWS Secrets Manager indexed by portalId, restricted decrypt IAM to only the integration service, and implemented synchronous token deletion on uninstall webhook. Resubmitted and certification approved on the next pass.

A legacy account-scoped credential that granted full read/write access to a HubSpot portal's data. Deprecated in November 2022. Cannot be generated for new accounts in 2026. Existing legacy API keys still work in some accounts but HubSpot has been migrating customers off them (HubSpot Developers documentation).

API keys (legacy) were single, long-lived account credentials. OAuth access tokens are short-lived, scoped to specific permissions, tied to a specific app installation in a specific customer portal, and refreshable. OAuth is the current standard for Marketplace apps; API keys are deprecated.

A Private App is a HubSpot-account-scoped integration that generates a long-lived access token for that single portal. Best for internal integrations where one company connects their own HubSpot to their own tooling. Not allowed for Marketplace apps; those must use OAuth.

No. Private App tokens are scoped to one portal and don't support the multi-tenant pattern Marketplace apps require. Marketplace apps must use OAuth.

Access tokens last roughly 6 hours. Refresh tokens are long-lived but can be revoked when customers reinstall your app or when HubSpot rotates them. Refresh access tokens before expiry on a schedule plus on detected 401s.

Encrypted at rest (field-level encryption in a database, or in a secrets manager like AWS Secrets Manager / GCP Secret Manager / Vault), accessible only to the services that need them, with audit logging on access. The May 2026 HubSpot security questionnaire asks about this.

HubSpot calls your registered Uninstall App API endpoint. Your handler should delete the access and refresh tokens immediately (not on a delayed cleanup job). Leftover tokens after uninstall are flagged in certification review.

Sunny Chauhan is the founder and CEO of Appnigma AI, a no-code platform that generates Salesforce AppExchange-ready Managed Packages from natural-language prompts. He holds Salesforce certifications in Platform Developer II, Platform App Builder, Administrator, Data Cloud Consultant, and AI Associate. Appnigma's approach to Salesforce Connected App OAuth (encrypted token storage, refresh-before-expiry, sync deletion on uninstall) transfers directly to the HubSpot OAuth patterns described above.

Originally published June 18, 2026. Last reviewed June 18, 2026. Authentication mechanism descriptions verified against HubSpot's intro to auth documentation and Marketplace certification security requirements current as of the published date.

• HubSpot OAuth and Scopes Complete Reference

• HubSpot Webhooks Implementation Guide

• HubSpot API Rate Limits Guide

• HubSpot Sandbox Setup Guide

• HubSpot Custom Integration Build Guide

• HubSpot Integration Platform Architecture Patterns

1/ HubSpot Developers, Introduction to Authentication 2/ HubSpot Developers, Private Apps Documentation 3/ HubSpot Developers, OAuth Quickstart 4/ HubSpot Marketplace Certification Requirements

How are your HubSpot tokens stored today, and could you defend that to the May 2026 security questionnaire?