Configure user-level access for an app (BETA)

User-level access is an alternative, more granular option to the account-wide access apps grant to users in your HubSpot account.

User-level vs. account-level access

Account-level access provides a uniform level of access for all users in your HubSpot account, while user-level access links your app’s features and API access to the associated per-user permissions in your account. When user-level access is set up, each user that meets your app’s configured scopes that correspond to their in-app permissions can install the app. If your app should behave differently based on who is using it, then you should opt for user-level access. Otherwise, account-level access remains the right choice for other use-cases such as account-wide automation, or syncing data across many tools in your account.

Set up user-level access for your app

To turn on user-level access for your app, add isUserLevel: true to the config property in your app’s top-level app-hsmeta.json file:

{
  "uid": "your-app-uid",
  "type": "app",
  "config": {
    "name": "Your App Name",
    "distribution": "marketplace",
    "isUserLevel": true,
    "auth": {
      "type": "oauth",
      "redirectUrls": [
        "http://localhost:4000/oauth2/hubspot-callback"
      ]
    }
  }
}

If isUserLevel is set to false or left unspecified, your app will use account-level access. Once you finish updating your app’s configuration and upload your project, any user who installs your app will have their actions annotated with [User] via [app name] in HubSpot’s app audit logs.

Please note: existing apps using account-level access cannot currently be migrated to user-level access. You’ll need to create a new app with user-level access to leverage this functionality.

Supported platform features

The sections below outline the platform feature support for user-level access.

Platform features

Feature	Account-level	User-level
APIs	Yes	Yes (partial)
MCP	No	Yes
App pages	Yes	Yes (partial)
App cards	Yes	No
App settings	Yes	Yes (partial)
`hubspot.fetch()`	Yes	Yes
UIE hooks	Yes	Yes
Serverless functions	Yes	Yes
Webhooks (v3, v4)	Yes	No
Custom workflow actions	Yes	No
Agent tools	Yes	No
App events	Yes	No
App objects	Yes	No
CMS	Yes	No
SCIM	Yes	No

All distribution options and authentication methods support user-level access.

UI extension point support

For app pages and app settings, you’ll need to set up and manage a separate backend service yourself to provide user-specific functionality and ensure you’re not sharing data between individual user installs.

API support

The following REST APIs are currently supported with user-level apps:

​User-level vs. account-level access

​Set up user-level access for your app

​Supported platform features

​Platform features

​UI extension point support

​API support

User-level vs. account-level access

Set up user-level access for your app

Supported platform features

Platform features

UI extension point support

API support