API calls to HubSpot


We want to send API calls to HubSpot, when leads register, unsubscribe and etc, so that the data is synced between HubSpot and our server side.
I’ve looked into HubSpot’s documents, and not sure which authentication we should use.

It seems Oauth authentication is user based, and requires user to grant access on the authentication URL.
While what we want is server based, like we store the API key/secret on our server, and use it to send requests to HubSpot API.
I feel API keys fits more to our needs, but I found this in HubSpot documents “API keys are great for rapid prototyping, but for security and commercial use, all integrations should use Oauth”, could you explain what we should use?


@adam.jernejec OAuth 2.0 is the much more secure way of doing it. OAuth isn’t as much user based as it is app based. You will make an “app” in a HubSpot Developer’s portal and then when you install that app on your marketing portal you will get an access token and a refresh token. You can store both of those server side to make your calls to the HubSpot API.


Hey @pmanca, if we store the access token and refresh token on our server, do we need to refresh the access token every 6 hours? Also, to retrieve the access token and refresh token, it requires redirecting URL and asking user to grant access, which is not we want. What we need is just to sync contacts data between HubSpot and our server side. The question is more about authentication with OAuth 2.0 VS API keys, since I found this thread.

Thank you!


The API keys should work but are definitely less secure.

Yes, though, the OAuth method will require you to create a return URI processor which can capture and process the response from the web authorization page.

If you can’t do this, then you’ll have to use the API key.

The access tokens typically expire after 24 8 hours. When first generated you will get an expires_in in seconds, and you can use that to calculate out the expire time from the current timestamp and then fetch a renewed access_token with the refresh_token - and so on. You can technically now also query your access_token in the API to see a live expires_in value if you don’t want to run the calculation yourself.


Hey @Silarn, thanks for your response.

What are the concerns or reasons that API keys are less secure?

Another question is, is there a staging/sandbox app we can create on HubSpot for testing? And can we create separate API keys for the testing app?



API Keys are essentially master keys to the API. There’s no way to restrict access by user account or app. You simply generate your key and then pass it as part of the API request. While this should be encrypted, all someone has to do is get access to this one key and the door is unlocked.

With OAuth, you start with an app which will generate a client and secret key. You use these in combination with a scope to generate a URL requiring a user to log into their account and approve the access levels defined by the scope. (And if they don’t have permissions for those scopes, then they won’t be able to authorize it.) You then retrieve an access token (requiring several identical bits of info from the original request) which expires and must be renewed (with a separate refresh token) every 24 8 hours. You only pass the secret with the original auth request, which reduces the possibility of it being intercepted. If someone manages to get your access token, the scope is hopefully restricted and will only last at most another 24 8 hours.

Essentially it’s much more difficult to crack and get unfettered access to the API. (It also allows you to create apps which can grant access to any Hub, while API tokens are tied to a specific Hub account.)

It should be possible to create developer portals which allow you to create temporary test portals. I’m not sure if they have complete API coverage, as I’ve never used one personally.

Edit: It was 8 hours, sorry. :flushed: