Hannah BeattyTL;DR: Time is running out to replace your HubSpot API keys with private or public apps to ensure custom functions and integrations keep working to power your business.
8/30/22 Update:
If you use API keys in HubSpot we have an important message: they're going away on Nov. 30, 2022.
You're bound to have plenty of questions.
- "What the heck does ‘API’ even mean?"
- “Hey, I get emails about them from HubSpot! What do we use them for?”
- “Are they really that important?”
- “Why do I keep getting a message about ‘rotating’ these keys?”
- “Can someone just deal with this for me?”
Below you'll find careful explanations vetted by our top-tier development team and translated into an approachable language anyone can understand. (Especially those who think of snakes when they see the word, "Python.")
Table of Contents
What You Actually Need to Know About HubSpot API Keys
The "API" in API Key stands for application programming interface.
Think of APIs in general as types of doors that connect two or more computer programs in order for them to communicate back and forth. As they pass information to and fro, the door needs to be open, of course.
An API key is like the master key that opens these revolving doors and gives other tools you use unrestricted access to your HubSpot portal.
Using API keys to give unrestricted access to HubSpot is far less granular than other methods where you must pick and choose what parts of your portal you want to connect to outside apps.
API Keys have been the authentication method of choice for HubSpot since the dinosaurs roamed the earth. And while HubSpot specifically would prompt Super Admins to "rotate the key" every six months to improve security, they have not gone without frustration and data breaches.
Which leads us to exit, stage left.
HubSpot API Key Sunset
On June 1, 2022, HubSpot announced that within six months, HubSpot API Keys would no longer be functional as of November 30, 2022.
We had big feelings about this… and so did quite a few others.
When we say that API keys will no longer be functional, imagine all the doors in your entire house locked and the keys just disappeared.
If the clock strikes midnight on November 30, 2022, and you have API keys that weren't properly transitioned, anything that you used the keys to connect will simply stop working.
So, custom-coded workflows, custom applications, serverless functions, custom CRM object syncs, software integrations and more could all just break down.
Despite the time crunch and the disastrous effects if you do not integrate in time, the decision is ultimately net positive to improve security and privacy. Let's get to work.
The Replacement for HubSpot API Keys
HubSpot API keys were one of the three ways to integrate external apps to a HubSpot portal. The two others, which are not going away, are private apps and public apps.
Both private apps and public apps allow for the user to set scopes, or permission parameters, that allow your developer to choose what parts of HubSpot it needs to share with other apps (rather than granting access to the whole shebang).
What allows for the specific permissions? OAuth.
HubSpot describes OAuth as: “a secure means of authentication that uses authorization tokens rather than a password to connect your app to a user account.”
Public and private apps allow users to break down and understand where requests are coming from in order to limit the scopes.
These two methods are mostly interchangeable with some key differences.
Private Apps
Private apps were released by HubSpot in November 2021.
| Pros | Cons |
| A portal can have more than one private app, which allows for greater flexibility in determining access control. Ideal for testing. |
However, a private app itself can only be installed on a single account. It also does not support extensions, custom timeline events or webhooks. |
✨Private apps are the HubSpot recommended replacement for API Keys.✨
Public Apps
Public apps are the second option available.
| Pros | Cons |
|
Public apps can be used by multiple HubSpot accounts. You can list this app on the HubSpot App marketplace — allowing other HubSpot users to purchase and use this same connection thanks to you. Webhooks, custom timeline events and extensions are supported by public apps. |
Individual access tokens expire after 30 minutes. |
How Do I Prevent System Outages on November 30?
The recommended course of action between now and November 30, 2022, is to migrate an existing API key to a private app.
In the simplest way possible here is how to do that:
-
Find all the places where an API key is being used.
-
Look at the call logs and audit logs on the API Key Page. Note that logs only show a week’s worth of activity so it’s recommended you review two weeks’ worth of calls to thoroughly see everything the API Key is being used for.
-
Document each unique call’s request method and path. This will help you determine the scopes you need for the next step.
-
Create one private app with all scopes for the time being (you can change this in the future).
-
Monitor to make sure no other calls are made using an API Key following the creation of the private app.
It goes without saying, but don’t wait until November 29, 2022, to start this process. Leave the last-minute requests to the kids who need to build a diorama of a national park for the next day’s class.
Okay, Then What?
Congrats! You have a new way to talk to the API, but the work doesn’t end there. Next steps include:
- Working backwards to determine where the call is coming from in your HubSpot portal (that’s why it’s important to document!).
- Swapping the secret in the code to the private app in the user interface or the command line interface (CLI).
Seem too complicated? Our team is standing by to ensure your company and integrations continue to function despite the HubSpot API Key sunset.
