HubSpot API Authentication: Methods & Security (2026)

Authentication overview

HubSpot API authentication provides the mechanisms to securely connect applications with HubSpot accounts, granting programmatic access to CRM, marketing, sales, and service data. The choice of authentication method depends on the application's nature: whether it's a public integration requiring user consent or a private, internal tool accessing a single HubSpot account (HubSpot Developer Docs). Proper authentication ensures data privacy, maintains data integrity, and controls the scope of access to HubSpot resources.

HubSpot's approach aligns with industry standards for API security, emphasizing the use of secure protocols like HTTPS/TLS for all communication to protect credentials and data in transit. Developers are guided to implement robust security practices to prevent unauthorized access and protect sensitive customer information.

Supported authentication methods

HubSpot API supports two primary authentication methods tailored to different integration scenarios:

1. OAuth 2.0: This is the recommended method for public applications, integrations sold on the HubSpot App Marketplace, or any application that needs to access multiple HubSpot accounts. OAuth 2.0 allows users to grant specific permissions to an application without sharing their HubSpot credentials directly. It provides a secure, token-based authorization flow (OAuth 2.0 Specification). HubSpot primarily uses the Authorization Code Grant type (HubSpot OAuth 2.0 documentation).
2. API Keys (for Private Apps): For applications that only need to access a single HubSpot account and are not intended for public distribution, HubSpot offers API keys associated with private applications. These keys provide direct access to the account's data and should be treated with the highest level of confidentiality. Private app API keys are suitable for internal tools, custom scripts, or integrations built specifically for one HubSpot instance.

The following table summarizes the key characteristics of each method:

Getting your credentials

To begin integrating with the HubSpot API, you must first obtain the appropriate credentials from the HubSpot Developer Portal:

For OAuth 2.0 (Public Apps)

1. Create a Developer Account: If you don't have one, sign up for a HubSpot Developer Account (HubSpot Developer Portal).
2. Create an App: Navigate to your developer account and create a new application.
3. Configure OAuth 2.0: Within your app settings, configure the OAuth 2.0 details. You will need to specify:
   • Redirect URLs: These are the URLs where HubSpot will redirect the user after they grant or deny permission to your app. You can add multiple redirect URLs, but they must be HTTPS.
   • Scopes: Select the specific permissions your app requires. Scopes define the types of data and operations your app can access (e.g., crm.objects.contacts.read, crm.schemas.contacts.write). Requesting only necessary scopes adheres to the principle of least privilege.
4. Retrieve Credentials: After configuration, HubSpot will provide you with a Client ID and a Client Secret. These are critical for initiating the OAuth flow.

For API Keys (Private Apps)

1. Access HubSpot Account: Log in to the HubSpot account you wish to integrate with.
2. Navigate to Integrations: Go to Settings > Integrations > Private apps.
3. Create a Private App: Click "Create a private app" and provide a name and description.
4. Configure Scopes: Just like with public apps, select the necessary scopes for your private app. This limits the app's access to only the required data and actions.
5. Generate API Key: Once configured, HubSpot will generate an Access Token for your private app. This token acts as your API key. It is displayed only once, so store it securely immediately.

Authenticated request example

Once you have obtained an access token (either an OAuth 2.0 access token or a private app access token), you can use it to make authenticated requests to the HubSpot API. The access token is typically included in the Authorization header of your HTTP requests as a Bearer token (RFC 6750).

Here's an example using curl to retrieve contacts:

curl -X GET \
  'https://api.hubapi.com/crm/v3/objects/contacts?limit=10' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Replace YOUR_ACCESS_TOKEN with your actual access token. For privacy and security, access tokens should never be hardcoded directly into client-side code or publicly accessible repositories.

HubSpot provides SDKs in several languages, including Node.js and Python, which abstract much of the authentication complexity. For example, using the Python SDK:

from hubspot import HubSpot
from hubspot.crm.contacts import SimplePublicObjectInput, ApiException

# Replace with your actual access token
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

# Initialize the HubSpot client
api_client = HubSpot(access_token=ACCESS_TOKEN)

try:
    # Fetch contacts
    api_response = api_client.crm.contacts.basic_api.get_page(limit=10)
    print(api_response.results)
except ApiException as e:
    print("Exception when calling ContactsApi->get_page: %s\n" % e)

Security best practices

Adhering to security best practices is crucial when integrating with any API, especially one handling sensitive customer data like HubSpot's:

• Protect your credentials: Never hardcode API keys or client secrets directly into your application code. Use environment variables, secure configuration files, or secret management services (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault) (AWS Secrets Manager documentation).
• Use HTTPS/TLS: Always ensure all communication with the HubSpot API occurs over HTTPS to encrypt data in transit and prevent eavesdropping. HubSpot's API inherently enforces HTTPS.
• Least Privilege: Request only the minimum necessary OAuth scopes or private app permissions required for your application to function. Avoid requesting broad access if granular permissions are sufficient. Regularly review and revoke unnecessary permissions.
• Secure OAuth Redirect URIs: Ensure your OAuth redirect URIs are specific and secure (HTTPS). Avoid using wildcard URLs, and validate the state parameter during the OAuth flow to prevent CSRF attacks.
• Refresh Tokens Securely: For OAuth 2.0, store refresh tokens securely and use them to obtain new access tokens when the current one expires. Access tokens have a limited lifespan, and refresh tokens enable long-term access without re-authenticating the user.
• Error Handling and Logging: Implement robust error handling for API calls, especially authentication errors. Log relevant information (without exposing sensitive data) to monitor for unusual activity or potential security incidents.
• Regular Audits: Periodically review your application's access to HubSpot, including active API keys and OAuth connections. Revoke credentials that are no longer in use or if a compromise is suspected.
• Input Validation: Sanitize and validate all user inputs before passing them to the HubSpot API to prevent injection attacks and other vulnerabilities.