Please note: starting November 30, 2022, HubSpot API keys will no longer be able to be used as an authentication method to access HubSpot APIs. In addition, starting July 15, 2022, accounts without a HubSpot API key already generated will no longer be able to create one.

Instead, you'll need to use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Authentication methods on HubSpot

There are three ways to authenticate calls to HubSpot's APIs: OAuth, private app access tokens, and API keys

When building an integration, keep the following in mind:

  • While most endpoints support API key authentication, API keys provide both read and write access to all of your HubSpot CRM data, which can be a security risk if your key is compromised. To follow best practices, it's recommend that you use a private app access token or OAuth which both enable you to limit the data that your integration can request or change in your account.
  • Integrations designed for multi-customer use or listing on the App Marketplace must be built as an app using HubSpot’s OAuth protocol. 

Below, learn more about each method, including how to include it in your code for authorization.

The only difference between API keys in standard HubSpot accounts and developer accounts is the type of account that the key allows access to. Learn more about HubSpot's account types.

OAuth

To make a request using OAuth, include the OAuth access token in the authorization header:

/~curl --header "Authorization: Bearer C4d***sVq" https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false

Private app access tokens

Similar to OAuth, to make a request using a private app access token, include the token in the authorization header:

/~curl --header "Authorization: Bearer ***-***-*********-****-****-****-************" https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false

API key

To make a request using an API token, add to key in a hapikey= query parameter:

/~curl 'https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false&hapikey=456***cfa'

When developing on HubSpot, you might prefer to work in your own HubSpot testing environment before working in a production account. To do this, you can create a developer account. With a developer account you can build an app and authenticate it using OAuth, and each account comes with a developer account API key, and create a test production account which has its own API key