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 should use OAuth - this is required for becoming a featured integration.

Unless otherwise mentioned in the documentation for a specific endpoint, all endpoints support both OAuth and API keys. Below are examples of making the same request (using cURL), with different types of authentication. Aside from the authentication used, 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 CJSP5qf1KhICAQEYs-gDIIGOBii1hQIyGQAf3xBKmlwHjX7OIpuIFEavB2-qYAGQsF4" 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\=demo

(Deprecated, but included for completness) Using OAuth v1, which uses the access_token= query parameter in the URL:

➜  ~ curl https://api.hubapi.com/contacts/v1/lists/all/contacts/all\?access_token\=demooooo-oooo-oooo-oooo-oooooooooooo

The best way to get started is by implementing one of these methods of authentication, both of which you can test out quickly in our demo portal:

  • Login: https://login.hubspot.com/login/?loginPortalId=62515
  • Username: testapi@hubspot.com
  • Password: HubSpot
  • API Key: demo
  • Hub ID: 62515

When you've moved past playing with the API and are ready to start developing in earnest, you can register your application by creating a developer account.

Once you've created your account and have OAuth credentials, it's time to start diving into initiating OAuth.

Docs for this section or API