OAuth2 Scope Design — Designing Effective OAuth2 Scope Hierarchies for APIs

In this tutorial, you will learn about OAuth2 Scope Design. We cover key concepts, practical examples, and best practices to help you master this topic.

OAuth2 scope design defines granular, consistent permission scopes that balance user comprehension with fine-grained access control, using resource:action naming conventions and scope hierarchies.

What You'll Learn

• Scope naming conventions (resource:action)
• Scope granularity trade-offs
• Scope hierarchy and implied scopes
• Scope management and documentation
• Scope deprecation and Migration

Why It Matters

Poor scope design leads to applications requesting overly broad scopes or users approving scopes they don't understand. Consistent scope naming and granularity improves security and user experience. DodaTech's scope hierarchy uses 50+ granular scopes with clear naming that reduced over-scoping by 70%.

flowchart TD
    A["Scope Design"] --> B["Resource-based"]
    A --> C["Action-based"]
    A --> D["Mixed (recommended)"]

    B --> B1["threats:read, threats:write"]
    B --> B2["reports:read, reports:write"]

    C --> C1["read:threats, write:threats"]
    C --> C2["admin:threats"]

    D --> D1["resources:actions"]
    D --> D2["threats:read, threats:write"]
    D --> D3["reports:read, reports:admin"]

    E["Good: threats:read"] --> F["Clear resource + action"]
    G["Bad: api_access"] --> H["Too vague"]

What's Next

Apply scope design to your {{< ilink "OAuth" "OAuth2 Scopes" }} implementation and combine with {{< ilink "OAuth" "OAuth2 Rich Authorization Requests (RAR)" }} for fine-grained authorization.