HubSpot Authentication: API Methods & Security (2026)

Authentication overview

HubSpot provides multiple authentication mechanisms to secure access to its APIs, ensuring that only authorized applications and users can interact with HubSpot data. The choice of method depends on the type of application being developed and the required level of access and security. The primary methods supported are OAuth 2.0 and API keys.

OAuth 2.0 is an authorization framework that enables an application to obtain limited access to a user's protected resources without exposing their credentials. It is the recommended method for most integrations, especially those developed for multiple HubSpot accounts or third-party applications. This protocol allows users to grant specific permissions to an application, which then receives an access token to make API requests on their behalf. The OAuth 2.0 specification is maintained by the Internet Engineering Task Force (IETF), as detailed in the RFC 6749 OAuth 2.0 Authorization Framework. HubSpot implements standard OAuth 2.0 flows, including the Authorization Code Grant flow, which is suitable for web applications.

API keys offer a simpler authentication method, primarily suitable for private applications, internal scripts, or development and testing purposes where the application operates on a single HubSpot account. While easier to implement, API keys carry a higher security risk if compromised, as they grant broad access to the associated HubSpot account. HubSpot refers to these as 'API keys' but they function as bearer tokens in most API requests, often passed in the Authorization header.

Understanding the distinctions between these methods is crucial for designing secure and efficient integrations with the HubSpot platform. HubSpot's official API documentation provides comprehensive guides on setting up and using each authentication type.

Supported authentication methods

HubSpot offers distinct authentication methods tailored for different integration scenarios:

• OAuth 2.0: This is the industry-standard protocol for authorization and the recommended method for public integrations, third-party applications, and private apps that require granular control over permissions and secure user consent. It involves redirecting the user to HubSpot to authorize the application, after which an access token and refresh token are issued. Access tokens have a limited lifespan (typically 30 minutes) and require a refresh token to obtain new access tokens without user re-authorization.
• API Keys: For applications that only need to access a single HubSpot account, such as internal tools or development scripts, API keys provide a straightforward authentication mechanism. These keys are long-lived tokens that grant access to account data. While simpler, they require careful handling to prevent unauthorized access.

Here's a comparison of HubSpot's authentication methods:

HubSpot also supports a specific type of OAuth 2.0 for "Private Apps", which are custom integrations built for a single HubSpot account. These private apps streamline the OAuth flow by pre-approving access and generating an access token and refresh token directly within the HubSpot developer interface, bypassing the need for user redirection for authorization. This combines the security benefits of OAuth 2.0 (scoped permissions, refresh tokens) with the simplicity of API key setup for internal tools, as detailed in the HubSpot developer API overview.

Getting your credentials

To obtain credentials for HubSpot API authentication, you will use the HubSpot Developer Portal:

For OAuth 2.0 (Public Integrations / Third-Party Apps):

1. Create a Developer Account: Navigate to the HubSpot Developer Portal and create an account or log in.
2. Create an App: From your developer account dashboard, create a new app. You'll need to provide details such as the app name, description, and branding.
3. Configure OAuth: In your app settings, go to the "Auth" tab. Here you will define:
• Redirect URLs: The URL(s) to which HubSpot will redirect users after they authorize your application.
• Scopes: The specific permissions your app requires (e.g., crm.objects.contacts.read, crm.objects.deals.write). Choose the minimum necessary scopes to adhere to the principle of least privilege.
4. Client ID and Client Secret: HubSpot will generate a Client ID and Client Secret for your app. The Client ID is public, but the Client Secret must be kept confidential.
5. Authorization URL: Construct the authorization URL using your Client ID, Redirect URL, and requested scopes. This URL initiates the OAuth flow when a user connects their HubSpot account to your app.

For OAuth 2.0 (Private Apps):

1. Access a HubSpot Account: Log into the specific HubSpot account for which you want to create a private app.
2. Navigate to Integrations: Go to Settings > Integrations > Private apps.
3. Create a Private App: Click "Create a private app".
4. Configure Permissions: Define the necessary API scopes/permissions for your private app. Similar to public apps, select only the permissions required for your application's functionality.
5. Generate Access Token: Once configured, HubSpot will generate an access token and refresh token for your private app. These tokens can be directly used in your API requests. The access token will expire, but the refresh token can be used to obtain new access tokens.

For API Keys (Legacy or Simple Internal Use):

1. Access a HubSpot Account: Log into the HubSpot account.
2. Navigate to Integrations: Go to Settings > Integrations > API key.
3. Generate API Key: Click "Create API key". HubSpot will generate a unique key.
4. Copy and Store Securely: Copy the API key immediately and store it securely. HubSpot only displays the key once.
5. API Key Deprecation: Note that HubSpot has been moving towards deprecating API keys in favor of OAuth 2.0 (including Private Apps) for enhanced security. While still functional for some endpoints, it is advisable to transition to OAuth 2.0 for new integrations or when possible, as outlined in HubSpot's guide on private apps.

Authenticated request example

After obtaining an access token (either via OAuth 2.0 flow or a private app), you include it in the Authorization header of your API requests as a Bearer token. For API keys, they are also typically passed in the Authorization header.

Using an OAuth 2.0 Access Token (or Private App Token)

Here's an example using curl to retrieve contacts:

curl -X GET \
  https://api.hubapi.com/crm/v3/objects/contacts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Replace YOUR_ACCESS_TOKEN with the actual access token obtained from your OAuth 2.0 flow or private app. The specific API endpoint (/crm/v3/objects/contacts) will vary depending on the HubSpot API you are interacting with.

Using an API Key (Legacy Method)

If you are still using an API key (for legacy integrations or specific internal scripts), the request format is similar:

curl -X GET \
  https://api.hubapi.com/crm/v3/objects/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Replace YOUR_API_KEY with your HubSpot API key. Again, remember to consider the security implications and HubSpot's recommendation to use OAuth 2.0 where possible.

For programmatic examples in various languages, refer to the HubSpot API documentation, which provides SDKs and code snippets for Python, Java, .NET, Node.js, PHP, and Ruby.

Security best practices

Implementing secure authentication for HubSpot APIs involves several key practices:

• Use OAuth 2.0: Prioritize OAuth 2.0 for all new integrations and migrate existing API key-based integrations where feasible. OAuth 2.0 provides token expiration, refresh token mechanisms, and granular scope control, significantly reducing the risk associated with compromised credentials. The OAuth 2.0 website provides an overview of the protocol.
• Principle of Least Privilege: When configuring OAuth scopes or private app permissions, grant only the minimum necessary access required for your application to function. Avoid requesting broad permissions if your application only needs to perform specific actions (e.g., read contacts, not write deals).
• Secure Credential Storage: Never hardcode API keys or client secrets directly into your application's source code. Store them in environment variables, secure configuration files, or a secrets management service (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager). Rotate credentials regularly.
• Protect Redirect URLs: For OAuth 2.0, ensure your redirect URLs are secure and explicitly defined. Only use HTTPS for redirect URLs to prevent interception of authorization codes.
• Validate State Parameter: When implementing OAuth 2.0, always use and validate the state parameter to prevent Cross-Site Request Forgery (CSRF) attacks. The state parameter should be a unique, unguessable value generated by your application before initiating the authorization request.
• Handle Tokens Securely:
• Access Tokens: Access tokens should be treated as sensitive data. Never expose them in client-side code or public repositories. Transmit them only over HTTPS.
• Refresh Tokens: Refresh tokens should be stored with even greater security than access tokens, as they can be used to mint new access tokens. They should be encrypted at rest and accessed only by trusted server-side components. Implement refresh token rotation if supported by HubSpot.
• Error Handling and Logging: Implement robust error handling for API authentication failures. Log authentication attempts and failures for auditing and to detect potential abuse. Be careful not to log sensitive credential information.
• Regular Audits: Periodically review your HubSpot integrations and their associated permissions. Remove any unused apps or API keys. Audit logs for suspicious activity related to API access.
• Stay Updated: Keep track of HubSpot's API changes and security recommendations, particularly regarding authentication methods and deprecations. Refer to the HubSpot changelog for updates.