Step-by-step guide how to create and use Private Apps in HubSpot

Did you know that you can use the HubSpot API to access very specific data in your account in a secure way? You can do this with HubSpot's Private Apps!

In this article, we'll teach you what Private Apps are, how you can create and use them to personalize your experience on the platform and get the most value from your data in HubSpot.

What are Private Apps?

In simple terms, Private Apps are a way to access specific data in a HubSpot account by generating an access token. These apps can only be used by the HubSpot account in which they were created and can only access the data and resources that have been granted to them through the scopes.

The Private Apps came to replace the "API Keys", before, API Key was the way to authenticate your application to use the HubSpot APIs, with this you could access and modify the data of your account. The problem with the API key was that it gave root access to all endpoints. So, if someone obtained that key, they would have access to all the information available through requests, without restrictions.

In fact, Private Apps are still an authentication mechanism through a token, however, they are different in terms of permissions, since you can limit the actions and the scope of the information to which they have access, for example, if you have an app that only requires reading the information of a contact you can grant only read permissions to contacts end point.

Create a Private App

To create a Private App you must have the corresponding configuration permissions and follow the steps below:

In your HubSpot account, click the settings icon in the main navigation bar.

In the left sidebar menu, go to Integrations > Private Apps.

Click the “Create a private app” button.

In the “Basic Info” tab, configure the details of your application: name, logo and description.

Now go to tab “Scopes”.

Here you will have a list with all the permissions that you can grant to your application, these are divided into four categories:

• CMS
• CRM
• Settings
• Standard

You can see the full scope list on the HubSpot site for more information. Once you have finished configuring your app, click the “Create app” button in the top right corner.

And that's it, you already have your Private App created! You can start making HubSpot API calls using the access token to get familiar with it.

Edit a Private App

Remember that you can always edit the configuration of your application in case you need to change information or scopes. Just click the “Edit details” button.

You can also change the access token; in case it is compromised you can rotate the token. A new access token will be created, and the original will expire. Simply click the “Rotate” button located in the “Access token” section of your application.

If your token is compromised and you want to revoke access immediately, click “Rotate and expire this token now”.

If there is no imminent threat to your token, it is still recommended that you rotate your token every six months. If you are ready to start a regular rotation of your token, click on “Rotate and expire this token later”, which will activate the token expiration in 7 days.

Delete a Private App

When you delete your Private App, its access token will be permanently revoked and you will no longer be able to use it to make API calls. To delete your app, click the “Delete Private-App” button in the last section of your app details.

Make API calls through your Private App

With your Private App created and configured, you are ready to make calls to the HubSpot API. Remember that the actions and information you have access to is limited by the permissions you defined.

All you need is the access token that you can check in the details tab of your application, just click on the “Show token” option.

Ok, now you can begin to carry out tests so that you become familiar with it.

NOTE: To make calls to the HubSpot API you must set the Authorization value in the header like this: “Bearer [YOUR_TOKEN]”. Bearer is a standard form of authentication used to identify an access token in an HTTP request.

Here are some ways you can make HubSpot API calls with your Private App:

Node.js & Axios

You can make a call to the contacts API using Node.js and axios as follows.

You can even create an instance to define your token just once and use that instance for all requests, like so.

Postman

You can make API call tests through Postman.

First you must indicate the type of HTTP request and the end point to which you want to make the call, in this case it is a "GET" type request to the "Contacts" end point.

Then, in the "Headers" tab you must add the "Authorization" key with the value "Bearer [YOUR_TOKEN]" that I previously mentioned.

Finally, click on the "Send" button, if the request was successful, you can view the information in the "Body" tab.

HubSpot Developers Site

On the HubSpot developer site you can see all the information about HubSpot APIs such as endpoints.

In this case we are going to access the section CRM > Objects > Contacts located on the left.

Now click the "Endpoints" tab to see the information of the end points available in the contacts API.

Here's a complete and detailed list of everything you can do in HubSpot's Contacts API, however that's a topic for another article. For now I want to show you an option to make your API calls.

In each of the end points you can find the "Test call" button located in the upper right corner.

You just have to select the authentication method “Private app access token” and paste your token. If the request is successful, you can view the call data in the "Response" tab.

Workflows in HubSpot

The previous ones were examples to practice and experiment with your Private App, however, here I want to give you an approach of how you could use it in the real world. In HubSpot workflows, you can use custom code to write and run custom code that extends the workflow's functionality inside and outside of HubSpot.

HubSpot makes available a number of libraries that help you perform complex actions more easily, for example, if you're using the Node.js client library, you can instantiate an OAuth client by passing the token from access to your application.

NOTE: Private Apps access tokens are implemented using the OAuth protocol as a base.

In this way, that instance that you created would already have the access permissions that you granted to your Private App, that is, you can now use the methods that the library offers you to manipulate the information.

Now, if you think about it, including your access token in the lines of a code that can be broken is very dangerous, anyone who gets access to it could steal the token and use it to access your data. But don't worry, there is a solution and that is why I wanted to show you the topic of Private Apps in workflows, HubSpot includes an option called "Secrets" in custom codes.

HubSpot custom code secrets are used to authenticate and authorize access. These are stored in a protected area and you can access them through environment variables in your custom code. In this way your tokens will be encapsulated in an additional layer of security.

Simply select “Choose a secret” press the “Add secret” option and now give your secret a name and the value that in this case will be the access token of your Private App.

That’s it! In “Secrets” you can see the list of your secrets and now you can use it in your code. (You can use multiple secrets in the same custom code)

Here's an example using the HubSpot client library to archive a contact by their ID with the "TEST_SECRET" environment variable.

View API call logs

HubSpot API calls are limited depending on your HubSpot subscription.

To review the calls to the API that your application has made, you must access the "Logs" tab of your Private App and here you will have a list of the calls with method, response, and period filters.

In the "Security" tab you will have a list with the date and the user who has manipulated the access token at a certain time.

HubSpot Private Apps are an ideal solution for businesses that want to improve their efficiency and productivity by using tools that are customized and specific to their needs. These private apps allow users to access their resources and automate tasks, saving valuable time and resources.

When creating a Private App, it is important to consider careful planning as proper security practices must be followed to ensure sensitive data and secrets are protected.

In short, HubSpot Private Apps are a great option for businesses looking to personalize their experience on the HubSpot platform while improving their efficiency and productivity.