In 2021 we embarked on a mission to overhaul the permission and auth system that underpins HubSpot apps. This system had grown organically over years without orchestration, and had become a significant technical and usability problem.
The Problem
HubSpot apps use OAuth as a system for developers to tell users what data their app will be accessing. "Scopes" are the smallest units of permission that developers use for this. Developers choose scopes in their app configuration, app users see a view of those scopes when installing the app.
Over time, the scopes collection had become a source of confusion and security risk for both developers and end users. Developers struggled to determine which scopes their apps needed, often resorting to trial and error due to unclear naming and lack of coherent hierarchy. For app users, scope approval was a guessing game. Broad, misleading permissions like "contacts" granted access to far more data than expected, creating trust issues and security concerns. This lack of granularity made it difficult to build secure, least-privilege applications, leading to unnecessary data exposure and friction in the app integration process.
My Approach
This project had several major components: An information architecture overhaul, a redesign effort for both developer tooling and app install UX, and a complex self-serve migration and rollout process.
Every UX problem is an IA problem
I began this project with an audit of the dozens of existing scopes and the hundreds of internal systems and data surfaces those scopes gave access to. Working with engineering and content design partners, we workshopped this over several days and came up with a first draft of a new app permission IA that aligned with our user-facing product structure. We decided that the "tag" for every scope would follow the same structure:
We then mapped our new proposed scope model onto the legacy scope model. This step was critical so that we had a clear path for developers to migrate their existing app configuration to the new system.
Supporting a major migration
Redesigning the scope system required a seamless migration path for developers updating their apps. Given the complexity of OAuth permissions, we focused on minimizing friction and reducing uncertainty in the process. The migration UI would guide developers step by step, clearly mapping old scopes to new granular ones, with explanations and recommendations to simplify decision-making.
Usability testing to validate
Before development, I conducted a task-based usability study to validate this migration flow. We recruited internal and external developers to walk through the new process, observing where they hesitated or needed clarification. Testing revealed that some scope descriptions were still too ambiguous, leading us to refine copy and introduce contextual tooltips for added clarity. Overall, the feedback confirmed that the new structure significantly improved understanding, and the guided migration approach helped developers feel in control of their app permissions. These insights gave us confidence before rolling out to private beta.
