Authentication Overview

HubSpot's APIs allow for two means of authentication, OAuth and API keys.  API keys are great for rapid prototyping, but for security and commercial use, all integrations designed for use by multiple HubSpot customers should use OAuth—this is a requirement to be listed in our App Marketplace.

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 both methods of authentication. 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 -H "Authorization: Bearer C4d***sVq" 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.