Understanding Declarative Scope Groups for HubSpot App Development

Hey, y'. All. I just wanted to do a quick walkthrough of the declarative scope groups UI and explain some of the context behind it. So I mentioned you can add additional scopes to the ui. What are these scopes and how do they behave? Um, so we can consider these scopes to be in three different groups. So again, these three types of scopes already exist, and they can be used, they're just not all configured in the ui. So first, there are required scope groups. These are required for all installs, and these are the scopes that are currently configured in the ui. These scopes must always be included in the install URL behind the scope equals parameter, and users installing the app must have access to these scopes. If the developer adds an additional scope to the install URL behind the scope equals parameter, then they're using conditionally required scopes. These scopes are not required to be in the install URL. So URLs that don't include conditionally required scopes will still succeed during installation. But if they are included in the install URL and the user or the account doesn't have access to them, then the installation will fail, just like they would for required scopes. And then finally, we have optional scopes. These scopes may be included in the install URL behind the optional scope equals parameter. If these scopes are in the URL, and if the user has access to them, the app will install with those scopes authorized. But crucially, if the user doesn't have access to an optional scope, the app can still be installed without those scopes being authorized. So these additional types of scopes, the conditionally required and optional scopes, are useful for features that only some HubSpot accounts have. For example, custom objects are only available for enterprise customers, so it can make sense to make custom object scopes optional so that both customers that have custom objects and those that don't can still install the same app. We're going to ask developers to declare all of the scopes their app could use and only allow installs with the scopes the developer has configured. But we don't want to immediately break apps that already use arbitrary additional scopes. So we've created a toggle called Turn on Advanced Scope Settings in the new ui. When this toggle is on, no arbitrary scopes are allowed, and any optional and conditionally required scopes must be defined. When the toggle is off, we match current behavior where any arbitrary scopes are allowed. So let's take a look at an existing app. This is an existing app, an app that was created a while ago, and you can see that the advanced scope settings are turned off. This means that the behavior of this app hasn't changed. I can add arbitrary scopes to the install URL. So let me go ahead and test this out. I can take the install URL, paste it into the into the search bar, and I can go ahead and add an additional scope. Let me add an optional scope or tickets, and you can see that I'm able to install it. Even though I haven't declared any optional scopes, it was just added to the URL and I'm still able to install the app with this optional scope. To enable the new declarative scopes policy, let me turn this toggle on. This will be required for all apps in about six months, and now that I've turned the toggle on, you can see the additional scope categories here. I can see that there are zero conditionally required scopes and zero optional scopes, and all of my previously selected scopes are still in the required scopes category. If I use the same URL from last time that includes an optional scope, it won't work. I see an error that there's a scope mismatch. This is because I am requesting an optional scope that hasn't been declared yet. So let me go ahead and declare that ticket scope as optional so I can go ahead and search for it, select it, and choose the category as optional. Let me update and save. And now when I go back to the original URL that includes the optional scope, it should work, and again it works and it lets me through. So going back to the toggle, I'm unable to turn it off right now because I'm actively using optional scopes. If I delete the optional scope, the snap becomes enabled and I can turn it off. If I try to turn it off, a modal appears that warns me that this will soon be required. Just to encourage developers to keep this on for now, that is an existing app. I also wanted to show new apps so in this new ui, new apps will automatically have the toggle on by default, just to encourage new apps to adopt the new scope policy. In addition, you'll notice that for new apps, the OAuth scope is automatically selected and can't be removed. We've always added the OAuth scope during installation on the backend, even if it wasn't declared. So this just cleans things up and doesn't break anything. So to wrap up, what does this mean for app developers? If your app currently requests scopes beyond the required scopes you've already configured in your app. You should turn the Advanced scope settings toggle on and list all of your conditionally required scopes and optional scopes. But if your app only uses the required scopes you've already configured in your app, the only action you need to take is turning on this toggle and then you're done. So that's all I have for you. Feel free to reach out if you have any questions. Bye bye.