Private apps

​

Create a private app

• 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.
• At the top of the page, click Add new scope.
• In the right panel, select the checkbox for each scope you want your private app to be able to access.
  • You can also search for a specific scope using the Find a scope search bar. You can review a full list of available scopes in this reference article.
  • Click Update when you’re done adding scopes. If you later decide that your app requires additional scopes, you can also configure them after your app is created.

• Review the scopes you’ve selected for your app. If you decide your app does not require a specific scope, you can click Delete next to that scope to remove it. You can also click Summary of selected scopes to view a breakdown of your app’s scopes and the associated access granted for each one.

• To subscribe to events triggered by changes to CRM objects in your account, you can set up webhook subscriptions for your private app:
  • At the top of the page, Click the Webhooks tab.
  • Under Target URL, enter the URL that HubSpot will make a POST request to when events trigger.
  • Click Create subscription.
  • In the right panel, select the object types that you want to subscribe to, then select the events associated with those objects (e.g., created, merged, deleted, etc.) that will trigger HubSpot to send a request to the endpoint you configured.
  • If you select an object type that requires additional scopes you haven’t authorized, you’ll be prompted to add those scopes to your app.
  • If you select Property changed for the event type, you can then select any of the associated object properties that you want to subscribe to changes for.
  • Click Subscribe.

• If you don’t want your webhook subscriptions to be active immediately, or if you want to delete a subscription you mistakenly created, you can hover over the webhook and manage its status, unsubscribe to delete it, or review the subscription details. Learn more about using webhook subscriptions in a private app in this article.

• After you’re done configuring your app, click Create app in the top right.
• In the dialog box, review the info about your app’s access token, then click Continue creating.

​

Make API calls with your app’s access token

• 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 app.
• Click the Auth tab, click Show token to reveal your access token. Click Copy to copy the token to your clipboard.

• You can then paste the access token to provide it to your developers, or use it yourself as you develop your app. When making a call to one of the HubSpot API endpoints, set the value of the Authorization field to Bearer [YOUR_TOKEN]. For example, if you’re making a call to the Contacts API using Node.js and axios, the request would look like the following:

axios.get(
  'https://api.hubapi.com/crm/v3/objects/contacts',
  {
    headers: {
      Authorization: `Bearer ${YOUR_TOKEN}`,
      'Content-Type': 'application/json',
    },
  },
  (err, data) => {
    // Handle the API response
  }
);

• 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:

const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN });

​

View private app access token information

// POST request response body
{
  "tokenKey": {{accessToken}}
}

// Example response for GET request to /oauth/v2/private-apps/get/access-token-info
{
  "userId": 123456,
  "hubId": 1020304,
  "appId": 2011410,
  "scopes": ["oauth", "crm.schemas.companies.write"]
}

​

Rotate your access token

• In your HubSpot account, click the Settings page in the main navigation bar.
• Navigate to Integrations > Private Apps.
• Click the name of your private app.
• Next to your access token, click Rotate:
  • If your token is compromised and you want to immediately revoke access, click Rotate and expire now.
  • If there’s no imminent threat to your token, it’s still recommended that you rotate your token every six months. If you’re ready to initiate a regular rotation of your token, click Rotate and expire later, which will trigger an expiration of the token in 7 days.
    • If your app is ready to transition earlier, you can click Expire now.
    • If you decide you need more time, you can click Cancel rotation, which will cancel the expiration of the original token and revoke the new access token.

• A super admin initiated a rotation (either immediately or scheduled for 7 days from now).
• A super admin canceled a pending rotation.
• A super admin opted to expire an access token immediately by clicking Expire now instead of waiting 7 days for the token to expire.
• The app’s access token is about to expire in 24 hours.
• The app’s access token has been rotated and expired after 7 days.
• If you haven’t rotated your access token in over 180 days, super admins will also receive a reminder email to rotate your app’s access token.

​

View API call logs

• On the details page of your app, click the Logs tab.
• Review and filter your private app API calls:
  • Click the Method and Response dropdown menus to filter your historical API calls by request method or response code.
  • Click the start date or end date dropdown menus to narrow your call logs to a specific time range.
  • You can also search for specific calls by URL in the Search by request URL search box.

• To export the API call logs, click Export logs (CSV). Then, specify a date range (up to the past 30 days) and click Export.
• In the pop-up box, select the date range of API calls you want to export and click Export. You will receive an email with a download link when the export is ready.

​

Private app limits

​

Delete a private app

• In your HubSpot account, click the settings icon in the main navigation bar.
• Click the name of your private app.
• At the top of the page, click the Auth tab.
• At the bottom of the page, click Delete [name of your app].
• In the dialog box, type the name of your app to confirm its deletion, then click Delete.