Migrate an API key integration to a private app

If you've built an internal integration that uses a HubSpot API key, your API key provides both read and write access to all of your HubSpot CRM data, which can be a security risk if your API key is compromised. By migrating to a private app, you can authorize the specific scopes that your integration requires, which generates an access token that limits the data that your integration can request or change in your account.

Follow the steps below to migrate an existing API key integration to a private app. It's recommended you first use a test environment, such as a developer test account or sandbox account, before making changes in production. If you have questions while migrating your app, visit the Developer Community. 

For a video walkthrough of migrating an API key integration to a private app, check out the HubSpot Developers video below:

In this guide

• Create a new private app
• Update the authorization method of your integration's API request
• Verify requests and monitor logs
• Implementation examples

• In your HubSpot account, click the settings icon in the main navigation bar.
• In the left sidebar menu, navigate to Integrations > Private Apps.
• Click Create private app.
• On the Basic Info tab, configure the details of your app:
  • Enter your app's name.
  • Hover over the placeholder logo and click the upload icon to upload a square image that will serve as the logo for your app.
  • Enter a description for your app.
• Click the Scopes tab.
• Next, select the scopes to authorize based on the APIs that your integration uses. To find out which scopes your app will need:
  • Compile a list of HubSpot APIs that your existing integration uses.
  • For each API request, navigate to the associated developer documentation (e.g., the contacts API).
  • Click the Endpoints tab, then scroll to the endpoint your integration is using.
  • Under the Requirements section, locate the scopes required to use the endpoint. Whenever possible, you should opt for scopes listed under Granular scopes instead of the ones under Standard scopes. If no granular scopes are listed, use the standard scopes.
  • Back in the settings for your private app, select the Read or Write checkboxes next to the matching scopes. You can also search for a scope using the Find a scope search bar.
• After you're done selecting your scopes, click Create app in the top right. You can always make changes to your app after you create it.
• In the dialog box, review the info about your app's access token, then click Continue creating.

With your private app created, you can start making API requests using its access token. On the Details tab of the settings page of your private app, click Show token under your access token to reveal it.

Instead of using a hapiKey query parameter to make API requests, private app access tokens are included in the Authorization header of your request. When making a request, set the value of the Authorization header to Bearer YOUR_ACCESS_TOKEN. Unless otherwise noted, this method of authorization is compatible with all public API endpoints, including the legacy APIs listed on HubSpot's legacy developer documentation.

Your request may resemble the following:

Private app access tokens are implemented on top of OAuth, so you can also make authenticated calls with your access token using one of HubSpot's client libraries. For example, if you're using the Node.js client library, you can instantiate an OAuth client by passing in your app's access token. 

To complete the migration over to your private app, remove all references to the HubSpot API key from your code, and instead use the approach above to use your private app's access token. Depending on the request you're making, you may want to create a secret to store your token, rather than hard coding it in your requests. Using a secret will prevent your token from being exposed, such as when using a token in a serverless function. To store the access token as a secret:

• In the terminal, run hs secrets add secretName. It's recommended to name the secret something simple so that you can easily reference it in the future.
• Paste the access token into the terminal, then press Enter.

You can then access your secret as an environment variable. Learn more in the serverless functions example below.

To confirm that all references to your API key have been removed, you can check the call log in your HubSpot account:

• In your HubSpot account, click the settings icon in the main navigation bar.
• In the left sidebar, navigate to Integrations > API key.
• Review the most recent requests in the Call log tab to confirm that no recent requests have been made since removing all previous references over to use your private app's access token.

If you have a paid Marketing Hub account with marketing contacts, and you previously set contacts created by integrations using your API key as marketing contacts, you must also do the same for your private app:

• In your HubSpot account, click the settings icon in the main navigation bar.
• In the left sidebar, navigate to Integrations > Marketing contacts.
• Under Your connected apps, use the search bar to locate your private app, then click the Turn on to sync contacts as marketing contacts switch on.

Once you've finished setting up your private app and you've confirmed all references to your API key have been removed in your code, you can deactivate the key.

Once you've removed all references to the HubSpot API key in your code and replaced them with references to your private app's access token instead, no further code changes are required.

If you followed the steps above in a developer test or sandbox account, repeat the same process in your production account. Then, monitor your private app's API call logs and confirm that none of your app's requests return 400 errors:

• In your HubSpot account, click the settings icon in the main navigation bar.
• In the left sidebar menu, navigate to Integrations > Private Apps.
• Click the name of your private app.
• Click the Logs tab.
• Any unsuccessful API request that failed due to a missing scope will appear as a 403 error. If you access the runtime logs of your integration, the response from the corresponding API request should include an error message with details about any missing scopes.

• If you need to include a new scope for your private app:
  • Click the Details tab.
  • Click Edit details.
  • At the top of the page, click Scopes.
  • Select the checkbox next to any missing scopes, then click Commit changes in the top right when you're done.

Learn more about creating and managing private apps, along with their limits, in the private apps guide.

Below, learn more about common API key usages and how to migrate to private app access tokens instead.

If you’re using an API key within a serverless function, you can similarly use the private app’s access token for authentication. You'll need to ensure that the private app has the scopes that the function needs to execute. 

To authenticate a serverless function with a private app access token:

• On the Access token card, click Show token to reveal your access token. Then click Copy to copy the token to your clipboard.
  
• With your access token copied, create a new secret to store the token:
  • In the terminal, run hs secrets add secretName. It's recommended to name the secret something simple so that you can easily reference it in the future.
  • Paste the access token into the terminal, then press Enter.
• In your serverless function's serverless.json file, add the secret name to the secrets array:

• In your serverless function's JavaScript file, set the value of the Authorization header to Bearer secretName. For example, if you're making a call to the Contacts API using Node.js and axios, the request would look like the following:

Learn more about making API calls with your app's token.

If you’re using an API key for running one-time jobs, such as creating a property, you can instead create a private app and use its access token to authenticate the call. Once a private app is created, you can reuse its access token for any one-time jobs, as long as the private app has the proper scopes. You can update a private app’s scopes at any time from the private app’s settings in HubSpot. Or, you can delete the private app and create a new one specific to the job you need to run.

Instead of using an API key to create a custom object, you can instead create a private app and use its access token to authenticate the call, as long as the app has the necessary scopes. For example, when using Postman to create a custom object, set the authorization type to Bearer token, then enter the token into the Token field.

Learn more about creating a custom object using a private app on HubSpot's developer blog.

If you’re using an API key in a Custom code workflow action, you can instead use the private app’s access token, as long as the app has the necessary scopes. To make the update, open the custom action in the workflow editor, then make the following updates:

• First, add a new secret that contains the private app access token.
  
• Then update the action code with the new secret.