How to Connect to the Hubspot API

[This article has been updated with new information as of 6/15/19]

One of the first tasks you face when connecting your web app with hubspot's API is authentication.  There are two ways to authenticate depending on what you plan to accomplish. The first way is a protocol called 'OAuth' which verifies the developer and the user, then allows you to select a portal and get access to information for a given length of time.  After that time expires you can request more time with a key which is sent when you’re authenticated the first time. The second way is much easier on the developer but harder on the end-user in the form of security. HubSpot provides every portal with a unique API Key. The API Key can be found clicking on the settings icon  then click Integrations -> API key.  It is important to note that the method of authentication is not always up to the developer and both have their use cases.  Check out the HubSpot API Authentication Overview page to get more information and find out which you will need.

Authenticating with OAuth

If you’re new to HubSpot as a developer and looking to use OAuth as your method of authentication you must first create your app on the HubSpot developers site. This will set you up with all the app credentials you will need to pass along during the authentication process. A HubSpot user will have to add your app to their HubSpot portal to accept any OAuth authentication requests. When creating an app you can choose what information you want to be able to access from the users portal, and the user agrees to those terms when they add your application to their portal. Now on to authenticate!

The OAuth authentication process breaks down to four steps:

1. Build the authentication URL for your app, and send the HubSpot user to that URL. The user will be presented with a screen that allows them to grant access to your integration. If a user has multiple HubSpot accounts, they'll have the option to choose which account they're granting access for.

2. After the user grants access, they'll be returned to your app, with a code appended to the URL.

3. Use that code and your Client Secret to get an access_token and refresh_token. Use that access_token to authenticate any API calls that you make for that HubSpot account.

4. Once that access_token expires after 6 hours, use the refresh_token from Step 2 to generate a new access_token.

Now let’s go over the four steps to create an OAuth authentication request using some examples.

Step 1:

In your code send a GET request to 'https://app.hubspot.com/oauth/authorize/' and include the following variables.

• client_id   This is your unique identifier as a developer and is found your developer section.

• redirect_uri  This is where the user will be redirected to after the request. MUST BE HTTPS.

• scope This is the data you asked the user for access to and is found in your developer section.

Example:

Step 2:

The URL you just built will redirect your user to the page you specified with a request variable “code” which is needed to request the API tokens needed to create API requests.  

Example:

If there are any problems with the authorization, you'll get the error parameters instead of the code variable:

Step 3:

Now that we have our code let's request our API tokens and all the relevant information returned in a JSON response.

Example:

If successful, you will receive a JSON response with the tokens:

Don’t forget to store your refresh_token, because your access token expires in 6 hours.

Should you have any problems with the request, you'll receive a 400 response with an error message.

Step 4:

So you got your tokens but they expired after 6 hours. What do you do now? Refresh them. To do this, you need to make another POST request using the refresh token from your last successful API authentication.

Example:

https://api.hubapi.com/oauth/v1/token?grant_type=refresh_token&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&refresh_token=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

If successful, you will receive a JSON response with a new refresh_token and access_token that will expire in 6 hours:

If there are any problems with the request, you'll receive a 400 response with an error message.

Authenticating with an API Key

This method is the easiest but does pose some security risks should the API key become compromised. This key can be used on all endpoints in HubSpot including the delete methods.

The API Key can be found clicking on the settings icon  then click Integrations -> API key.

To use it just include it as a GET request variable called “hapikey”. Here is an example url which will return the last 100 things your contacts engaged in since Sunday, January 1, 2017 5:00:00 AM:

https://api.hubapi.com/engagements/v1/engagements/recent/modified?hapikey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=100&since=1483246800000

Conclusion

That sums up the authentication methods with HubSpot, Let us know if you run into any problems and we can try to help you solve them in the comments. Good luck!

Coding photo by Kevin Ku on Unsplash