Please note: starting November 30, 2022, HubSpot API keys will no longer be a supported authentication method for accessing 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 should 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.

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

Unless documentation for a specific endpoint says otherwise, all endpoints support both OAuth and API keys. Below are examples of the same cURL request using each authentication method. Aside from authentication, the requests are identical and would return the same results.

In each example, the request is being made to this endpoint (documented here):

GET https://api.hubapi.com/contacts/v1/lists/all/contacts/all

Using OAuth 2.0, which uses the Authorization header:

➜ /~curl --header "Authorization: Bearer C4d***sVq" 
 https://api.hubapi.com/contacts/v1/lists/all/contacts/all

Using a private app access token, which uses the Authorization header:

➜ /~curl --header "Authorization: Bearer ***-***-*********-****-****-****-************" 
https://api.hubapi.com/contacts/v1/lists/all/contacts/all

Using an API key, which is added to the URL using the hapikey= query parameter:

➜  ~ curl 'https://api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey=456****cfa'

API keys are great for rapid prototyping, but for security and commercial use, all integrations should strive to use OAuth. The best way to get started is by creating a developer account. From there, you can create test accounts, which have their own API keys, or create an app and get started with OAuth. 

Once you've created your account and have OAuth credentials, check out initiating OAuth and this Quickstart guide.