Docs

StudioHome

Roles & Permissions

Define roles with specific permissions grouped by resource.

Keywords

  • role - Define a role
  • permission - Define permissions for a resource

role Keyword

Roles group permissions together that can be inherited by agents.

Syntax

role RoleName {
    permission resourceName {
        action1,
        action2,
        action3
    }
}
✨ Edit in Studio

Common Permission Actions

ActionDescription
createCreate new resources
readView/read resources
updateModify existing resources
deleteRemove resources
listList multiple resources
searchSearch resources
executeExecute operations
manageFull management rights

Examples

Basic Role

role CustomerRole {
    permission products {
        read,
        search
    }
    permission orders {
        create,
        read
    }
}
✨ Edit in Studio

Admin Role

role AdminRole {
    permission users {
        create,
        read,
        update,
        delete,
        list
    }
    permission system {
        read,
        update,
        execute
    }
    permission reports {
        read,
        generate,
        export
    }
}
✨ Edit in Studio

Multi-Resource Role

role EditorRole {
    permission articles {
        create,
        read,
        update,
        delete
    }
    permission media {
        upload,
        read,
        delete
    }
    permission comments {
        read,
        moderate,
        delete
    }
    permission categories {
        read
    }
}
✨ Edit in Studio

Role Inheritance with Agents

Agents can inherit permissions from roles using the colon syntax:

role SellerRole {
    permission products {
        create,
        read,
        update,
        delete
    }
    permission inventory {
        read,
        update
    }
}

agent ProductManager: SellerRole {
    can list products
    can create product
    can update product when valid
    can delete product if not_in_orders
}
✨ Edit in Studio

Real-World Examples

E-Commerce System

role CustomerRole {
    permission products {
        read,
        search,
        filter
    }
    permission cart {
        create,
        read,
        update,
        delete
    }
    permission orders {
        create,
        read,
        cancel
    }
    permission reviews {
        create,
        read,
        update
    }
}

role SellerRole {
    permission products {
        create,
        read,
        update,
        delete,
        list
    }
    permission inventory {
        read,
        update,
        manage
    }
    permission orders {
        read,
        list,
        update
    }
    permission analytics {
        read,
        export
    }
}

role AdminRole {
    permission users {
        create,
        read,
        update,
        delete,
        manage
    }
    permission products {
        create,
        read,
        update,
        delete,
        manage
    }
    permission orders {
        create,
        read,
        update,
        delete,
        manage
    }
    permission system {
        read,
        update,
        configure,
        backup
    }
}
✨ Edit in Studio

Content Management

role ViewerRole {
    permission articles {
        read,
        search
    }
    permission comments {
        read
    }
}

role ContributorRole {
    permission articles {
        create,
        read,
        update
    }
    permission media {
        upload,
        read
    }
    permission drafts {
        create,
        read,
        update,
        delete
    }
}

role EditorRole {
    permission articles {
        create,
        read,
        update,
        delete,
        publish
    }
    permission media {
        upload,
        read,
        delete,
        manage
    }
    permission comments {
        read,
        moderate,
        delete
    }
    permission users {
        read,
        list
    }
}

role PublisherRole {
    permission articles {
        create,
        read,
        update,
        delete,
        publish,
        unpublish,
        schedule
    }
    permission media {
        upload,
        read,
        delete,
        manage
    }
    permission categories {
        create,
        read,
        update,
        delete
    }
    permission analytics {
        read,
        export
    }
}
✨ Edit in Studio

Project Management

role MemberRole {
    permission tasks {
        create,
        read,
        update
    }
    permission comments {
        create,
        read,
        update,
        delete
    }
    permission files {
        upload,
        read,
        download
    }
}

role ManagerRole {
    permission tasks {
        create,
        read,
        update,
        delete,
        assign
    }
    permission projects {
        read,
        update
    }
    permission members {
        read,
        list,
        assign
    }
    permission reports {
        read,
        generate
    }
}

role OwnerRole {
    permission projects {
        create,
        read,
        update,
        delete,
        archive
    }
    permission members {
        create,
        read,
        update,
        delete,
        manage
    }
    permission billing {
        read,
        update,
        manage
    }
    permission settings {
        read,
        update,
        configure
    }
}
✨ Edit in Studio

Best Practices

Naming Conventions

  • Role names: PascalCase + "Role" suffix
    • AdminRole, EditorRole, CustomerRole
  • Resource names: lowercase plural nouns
    • products, users, orders
  • Actions: lowercase verbs
    • create, read, update, delete

Permission Design

  1. Follow the Principle of Least Privilege

    • Grant only necessary permissions
    • Start restrictive, expand as needed

  2. Group Related Permissions

    role DataAnalyst {
    permission reports {
        read,
        generate,
        export
    }
    permission analytics {
        read,
        analyze,
        visualize
    }
}
    ✨ Edit in Studio

  3. Use Standard CRUD Operations

    • create, read, update, delete
    • Add custom actions when needed

  4. Organize by Resource

    role ModeratorRole {
    # Content resources
    permission posts { ... }
    permission comments { ... }
    
    # User resources
    permission users { ... }
    permission reports { ... }
}
    ✨ Edit in Studio

Common Patterns

Hierarchical Roles

# Basic access
role BasicUser {
    permission profile {
        read,
        update
    }
}

# Enhanced access (includes BasicUser permissions conceptually)
role PowerUser {
    permission profile {
        read,
        update
    }
    permission advanced_features {
        read,
        execute
    }
}

# Full access
role Admin {
    permission profile {
        read,
        update,
        delete
    }
    permission advanced_features {
        read,
        execute,
        configure
    }
    permission system {
        manage
    }
}
✨ Edit in Studio

Resource-Specific Roles

role ProductManager {
    permission products {
        create,
        read,
        update,
        delete
    }
}

role OrderManager {
    permission orders {
        read,
        update,
        cancel,
        refund
    }
}

role UserManager {
    permission users {
        create,
        read,
        update,
        suspend,
        delete
    }
}
✨ Edit in Studio

Read-Only Roles

role Auditor {
    permission transactions {
        read,
        list,
        search
    }
    permission logs {
        read,
        search,
        export
    }
    permission reports {
        read,
        generate
    }
}
✨ Edit in Studio

Integration Examples

With Agents

role OperatorRole {
    permission machines {
        read,
        operate,
        monitor
    }
    permission maintenance {
        read,
        schedule
    }
}

agent MachineOperator: OperatorRole {
    can start machine when authorized
    can monitor status
    must stop machine if emergency
    should report issues
}
✨ Edit in Studio

With Types and Workflows

enum DocumentStatus {
    draft
    review
    approved
    published
}

role ReviewerRole {
    permission documents {
        read,
        review,
        approve,
        reject
    }
}

workflow DocumentFlow {
    state draft -> review
    state review -> approved, rejected
    state approved -> published
}

agent DocumentReviewer: ReviewerRole {
    can review document when in_review
    can approve document if meets_criteria
    can reject document if issues_found
}
✨ Edit in Studio

Complete Example

# Multi-tier role system for a SaaS platform

role FreeUserRole {
    permission projects {
        create,
        read,
        update,
        delete
    }
    permission tasks {
        create,
        read,
        update,
        delete
    }
}

role ProUserRole {
    permission projects {
        create,
        read,
        update,
        delete,
        share
    }
    permission tasks {
        create,
        read,
        update,
        delete,
        assign
    }
    permission templates {
        read,
        use
    }
    permission integrations {
        read,
        configure
    }
}

role TeamAdminRole {
    permission team {
        create,
        read,
        update,
        manage
    }
    permission members {
        invite,
        read,
        update,
        remove
    }
    permission projects {
        create,
        read,
        update,
        delete,
        share,
        transfer
    }
    permission billing {
        read,
        update
    }
}

role PlatformAdminRole {
    permission users {
        create,
        read,
        update,
        delete,
        suspend
    }
    permission system {
        read,
        configure,
        backup,
        restore
    }
    permission analytics {
        read,
        analyze,
        export
    }
    permission support {
        read,
        respond,
        escalate
    }
}

# Agents using roles
agent ProjectManager: TeamAdminRole {
    can create project
    can assign tasks to members
    must monitor progress
    can generate reports
}

agent SupportAgent: PlatformAdminRole {
    can view user accounts
    can assist with issues
    must escalate when critical
    can access system logs
}
✨ Edit in Studio

Related Keywords

  • agent - Agents inherit from roles
  • visitor - Visitors may have associated roles
  • type - Types can include role references

Next Steps