Today we're releasing an update to the auth settings for public apps. This update will add new options for choosing the scopes used by your app. The new settings are currently optional, but they will be required beginning on October 21.

What's changing?

We're introducing new categories that must be selected when adding new scopes to your app. Currently, any scopes that are selected are treated as required, meaning that those scopes must always be included in the scope query parameter for all installations of your app. However, other scopes can be added to the scope parameter dynamically for specific installations, and the settings do not cover the optional scopes that could go in the optional_scope query parameter.

Going forward, the app settings will require you to pick one of these three categories when adding a scope to your app:

• Required scopes: Required for all installations of your app, and must be included in the scope parameter. This is the current behavior for scopes selected for the app.
• Conditionally required scopes: Can be optionally requested for certain app installs.  If the scope is being requested for the install, it can only be in the scope parameter, meaning that the scope must be approved for the installation to be completed. This will allow you to account for tiered features or scopes which are only required when users enable certain features in your app. 
• Optional scopes: Can be optionally requested for certain app installs. If the scope is requested for the install, it can only be in the optional_scope parameter, meaning that the scope can be excluded from the authorization if the account or user installing the app does not have the proper permissions for the optional scope (in which case it will not be included in the resulting refresh token or access tokens).

Including any scopes in your authorization URL that are not in your app settings will result in an error that there is a mismatch between the app scope settings and the install URL, blocking users from installing your app. Including a scope in the wrong scope or optional_scope parameter will also block installation of your app.

For existing public apps, the new settings will be disabled by default. These new categories can be enabled by turning on the advanced scope settings located at the top of the app scopes settings, at which point the new scope enforcement will be applied. Any scopes currently set up in the app settings will be set as required scopes to match the current behavior. 

The new advanced scope settings will be enabled by default for any new public apps.

This change will only affect new installations going forward. Changes to the auth settings will not affect existing installs or existing OAuth refresh tokens.

Why is this changing?

In addition to improving the security for public apps, this change paves the way for improving the installation process from the HubSpot App Marketplace. These new settings ensure that all of the permissions that an app may request are controlled in the settings for the app, while still allowing apps to dynamically request specific permissions depending on things like tiered features or user controlled functionality.

When is this happening?

Starting today, all new public apps will start with the advanced scope settings enabled, and the option to enable advanced scopes is available to all existing public apps.

Also beginning today, advanced scope settings will be required for any app applying to be listed in the HubSpot App Marketplace, as well as any apps applying for certification or going through the recertification process.

All apps will be required to use these new advanced settings by October 21. You will need to log into your HubSpot developer account and check the auth settings for your apps to make sure that all scopes are accounted for, otherwise your users may experience errors when installing your app.

Please see the public app creation and settings instructions for more details.

Please let us know if you have any questions by joining the discussion in our community.