Last modified: August 22, 2025
While building apps on the developer platform, you can configure authentication based on how you plan to install your app. HubSpot also provides local authentication tooling via the HubSpot CLI.

​
App authentication

There are two authentication types available based on how you plan to distribute your app: OAuth is required for multiple accounts, while static auth access tokens are used for installing in a single account at a time.

​
OAuth

If you plan to distribute your app to multiple accounts (either through listing on the HubSpot App Marketplace or by managing specific authorized accounts), your app must be built using OAuth authentication. You’ll need to set up and host an OAuth backend service (e.g., hosted as a Docker instance using a cloud service provider) to initiate the OAuth process and manage token data for users installing your app in their account. HubSpot provides a Node.js quickstart guide here, which includes code you can run in a Docker instance with full OAuth support. Authentication configuration details for your app are available on the app details page in the developer overview of your HubSpot account. Once you’ve set up an OAuth backend, you can make API requests using the OAuth access token that corresponds to a user who installed your app. This access token is provided using the Bearer HTTP authorization header. For example, if you wanted to retrieve contacts for the account with an access token of 00000000-aaaa-xxx-yyyy-zzzzzzzzzzzz, your request would resemble the following: 
curl --request GET \
--header "Authorization: Bearer 00000000-aaaa-xxx-yyyy-zzzzzzzzzzzz" \
--url "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false"
Configure your app to use OAuth by setting the type subproperty within the auth field of your app’s app-hsmeta.json config to oauth. You’ll also need to set the distribution property to marketplace or private based on how you plan to distribute your app:
  • marketplace: used if you want the app to be eligible for listing on the HubSpot App Marketplace.
  • private: used if you only want to install your app in a specific set of allowlisted accounts. If you choose this option, you can install your app in a maximum of 10 accounts at a time.
Learn more in the app configuration guide.

​
Static auth

If you want to limit distribution of your app to a single authorized account, you’ll use a static auth access token. This token can be found in your app settings. An example request is provided below using a placeholder static auth access token. 
curl --request GET \
--header "Authorization: Bearer ***-***-*********-****-****-****-************" \
--url "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false"
Configure your app to use OAuth by setting the type subproperty (within the auth field) in your app’s app-hsmeta.json config to static, and set the distribution field to private. Learn more in the app configuration guide.

​
Developer API keys

Some app features and settings require a developer API key, which is available in the developer overview of your HubSpot account. If a feature or endpoint requires a developer API key, it’ll be documented in the associated guide or reference article. You should provide your key as the value for the hapikey query parameter, often accompanied by the associated appId query parameter that corresponds to the app you want to make changes for. For example, the cURL snippet below provides an example of using the custom channel registration endpoint: 
curl --request POST \
--url "https://api.hubapi.com/conversations/v3/custom-channels?hapikey={YOUR_DEVELOPER_API_KEY}&appId={appId}

​
Scopes

Based on the HubSpot data and functionality that your app will require access to, you’ll provide a list of scopes in your app’s app-hsmeta.json authentication config. For example, if your app required access to create contacts, you’d need to include the crm.contacts.write. Learn more about scopes.

​
Local authentication

While you develop your app locally using the HubSpot CLI, you can use the hs account auth command. If you’re configuring local authentication for the first time, you can also use the hs init command. Learn more about [installing the HubSpot CLI]. A full list of CLI commands is provided here