API Keys and Security in HubSpot

HubSpot has shifted away from traditional API keys to a more secure approach based on private apps and tokens. Understanding this change will help you keep your integrations secure, reduce risk, and follow modern best practices for authentication.

This guide summarizes what changed, why it changed, and how you can adapt your existing tools and workflows with minimal disruption.

What Changed With HubSpot API Keys

The platform previously allowed account-wide API keys to authenticate requests. These were simple to use but created serious security concerns. To address this, HubSpot replaced API keys with more granular, token-based authentication tied to private apps.

Instead of a single universal key, each integration now uses its own credentials, permissions, and scopes. This makes it easier to control access and monitor activity.

Why HubSpot Deprecated API Keys

The move away from account-wide keys was driven by several security and governance needs:

• Reduced blast radius: Compromise of one integration no longer exposes the entire account.
• Granular permissions: You can grant only the specific scopes an integration needs.
• Improved auditing: Activity is traceable per private app, not just per portal.
• Modern standards: Token-based authentication aligns with current security best practices.

By default, this change encourages safer design patterns when connecting external systems to your data.

Key Dates and Impact on HubSpot Users

The deprecation rolled out in phases so teams could migrate gradually. Existing API keys stopped working after the transition period, which meant that integrations that were not updated to use tokens began to fail authentication.

If you maintain any custom integrations, legacy scripts, or third-party tools authenticated with an old key, you need to confirm they have been migrated to the new model.

How Authentication Works in HubSpot Now

Modern authentication relies on private apps and access tokens. Instead of copying a portal-wide key, you create a private app in your account and use the token generated there.

Using Private Apps for HubSpot Integrations

Private apps are the foundation of current authentication. Each private app has its own settings, scopes, and tokens.

A typical setup flow looks like this:

1. Create a private app in the account settings.
2. Assign scopes that map to the API domains you need.
3. Generate an access token for the app.
4. Store the token securely, never in client-side code.
5. Include the token in the authorization header of your API calls.

Because each app has separate permissions, you avoid giving every integration full access to your data.

Scopes and Permissions in HubSpot Private Apps

Scopes define which APIs and data areas a token can access. For example, you might grant read-only access to contacts but full access to tickets.

When configuring a private app, follow these principles:

• Least privilege: Only enable the scopes your integration absolutely requires.
• Separation of duties: Use different private apps for very different purposes.
• Regular reviews: Periodically review scopes and revoke anything no longer needed.

This structure makes compliance and auditing much easier than with a single all-powerful key.

Step-by-Step: Migrating from API Keys in HubSpot

If you previously relied on API keys, you need to update your code and configuration. The migration process is straightforward but must be done carefully to avoid downtime.

1. Inventory All Existing Integrations

Start by listing everywhere your old key was used:

• Custom back-end integrations or microservices
• Serverless functions or scheduled tasks
• Internal tools or dashboards
• Third-party systems that were manually configured

Document which endpoints each integration uses and what level of access it requires.

2. Create Private Apps in HubSpot

Next, create the private apps that will replace your key-based access:

1. Open your account settings and locate the private apps section.
2. Create a new private app with a descriptive name that reflects its purpose.
3. Select only the scopes required for that integration.
4. Generate and copy the token in a secure manner.

For security, avoid sharing tokens over insecure channels and restrict who can view or regenerate them.

3. Update Your Code to Use Tokens

Wherever your key was previously appended to URLs or query parameters, replace that pattern with an authorization header:

• Remove references to the old key.
• Add a standard bearer token header to each request.
• Store the token in environment variables or a secure secrets manager.
• Test calls in a staging environment before changing production.

This aligns your integration with modern HTTP authentication practices and reduces accidental exposure in logs or URLs.

4. Test and Monitor Your HubSpot Integration

After updating authentication, perform end-to-end testing:

• Validate that all required endpoints still respond as expected.
• Check that permission errors do not occur due to missing scopes.
• Enable logging and monitoring around failed requests.

Monitor application logs and dashboards closely during the first days after the switch to catch issues early.

Best Practices for HubSpot Access Tokens

The new approach is safer, but only if you manage tokens properly. Treat tokens with the same care you would give to passwords or SSH keys.

Secure Storage of HubSpot Tokens

Follow these security guidelines:

• Use environment variables or a dedicated secrets manager.
• Never hard-code tokens in source control.
• Restrict access to configuration files and deployment systems.
• Rotate tokens periodically or when team members change roles.

Also ensure that any logging or error handling does not print tokens or full headers.

Auditing and Governance in HubSpot

Private apps make it easier to understand who is accessing your data and why. To maintain control over time:

• Review active private apps on a regular schedule.
• Disable or delete apps that are no longer needed.
• Document business owners for each app and integration.
• Coordinate with security and compliance teams on access policies.

With this structure, it becomes easier to prove compliance for data protection and access control requirements.

Additional Resources for HubSpot Developers

For the full technical reference and official documentation, consult the original guide on the HubSpot blog at this page about API keys and authentication. It covers ongoing updates, deprecation timelines, and detailed examples.

If you need broader help designing integration architecture, security, or SEO-focused content around your platform usage, consult a specialist. One option is to work with experts at Consultevo, who support strategy and implementation for complex technical setups.

By migrating away from legacy keys and embracing private apps, you align your integrations with the current security model, protect your data, and ensure that your automation and reporting continue to run reliably within HubSpot.

Need Help With Hubspot?

If you want expert help building, automating, or scaling your Hubspot , work with ConsultEvo, a team who has a decade of Hubspot experience.

Scale Hubspot

“`