HubSpot supports two types of apps for OAuth: Public apps and private apps.
For the most part, all HubSpot APIs work the same whether used with a public app or private app.
Both private app tokens and public app access tokens can be used in the HTTP Authorization request header when making API requests. Both types of apps also use the same OAuth scopes to set the access allowed for an app, which helps keep HubSpot accounts secure by only using the specific permissions your app needs to function.
While public and private apps function similarly from a technical perspective, however, there are different features and use cases for each one. Here are some examples and recommendations of when to build a HubSpot public app or a private app.
When to build HubSpot public apps
Any app that’s intended for use by multiple HubSpot accounts should be built as a public app. Public apps support one-click connections to a HubSpot account, making it easy for a HubSpot user to connect your integration without needing to manually create an app and copy and paste any tokens.
If you want your app to be listed in the HubSpot App Marketplace, you will need to build a public app. This is a requirement for listing, and you will not be able to apply to the marketplace if your app is built for private app tokens.
Additionally, creating a public app is a requirement to utilize some of the HubSpot platform features. For example, if you want to use the Webhooks API or timeline events, you'll need to build your integration using a public app, since those are set up as a feature of your app. Public apps can also have a custom settings page that users can view in their HubSpot account, allowing them to update their app settings without leaving HubSpot.
Public apps use OAuth 2.0 for authentication, which means that individual access tokens are short-lived.
After making the initial connection, you receive both an access token and a refresh token. Access tokens are used to make the requests to the HubSpot API, but they expire after 30 minutes. You can use refresh tokens to generate new access tokens when the old one expires. This means your integration will need to have the infrastructure to securely store refresh tokens long-term, as well as manage and refresh the access tokens.
You can find more details about using OAuth 2.0 with HubSpot in our OAuth documentation.
When to build HubSpot private apps
Private apps can be used for custom integrations intended for use by a single HubSpot account. Keep in mind, though, that users will need to manually create a private app, set up the scopes, and then copy and paste the private token into your integration.
Private apps are a good option for one-off scripts or single API calls. For example, you can use a private app to create a new custom object, or to import CRM records from a CSV file if you’re using a script. You can create a private app with the appropriate scopes, use the token to make your API request or authenticate the requests in your script, and then delete the private app when you're done. This way, the token is invalidated as soon as you're done using it.
Private apps are a great option for integrations built directly in HubSpot as well. For example, you can use a private app token to authenticate API requests made in a custom code action in a HubSpot workflow. Private apps can also be used in CMS serverless functions, or code snippets in a chat bot. When used in HubSpot, private app keys can be securely stored as a secret and used to make API requests by referencing that secret.
You can use multiple private apps in a single HubSpot account, allowing you to split the traffic between different integrations or jobs. Each private app will have its own set of scopes, so you can make sure that each job is limited to the specific permissions it needs. For example, if you have multiple workflow code actions that all send data to the same external service, they can share the same private app token. If you have multiple integrations sending data between separate external services, on the other hand, you can use a separate private app for each of those external services.
Private app tokens work similarly to OAuth access tokens, but they don't expire. Tokens can be easily rotated if they are lost or otherwise compromised. All private apps in a HubSpot account collectively share the daily rate limit, but each private app will have its own separate burst limit. You can find more details about rate limits in our developer documentation.
Conclusion
From the perspective of making API requests to the HubSpot APIs, public and private apps are mostly interchangeable. If you're using one of the HubSpot API client libraries for your integration, both use the access token authentication type when creating the client, meaning that most of your existing code won't need to change to swap a private app to a public app. This makes it easy to create a private app for testing or prototyping, and then swap it to a public app before releasing it to the public.
If your app currently uses an API key, we have a guide for migrating your integration to a private app to help you update your app before API keys are no longer supported. However, if your app is used by multiple HubSpot accounts, you should consider making your app public to make it easier for customers to install.