Docs

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

Action	Description
`create`	Create new resources
`read`	View/read resources
`update`	Modify existing resources
`delete`	Remove resources
`list`	List multiple resources
`search`	Search resources
`execute`	Execute operations
`manage`	Full 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 {
    "list products"
    "create product"
    "update product"
    "delete product"
}

✨ 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

Follow the Principle of Least Privilege
- Grant only necessary permissions
- Start restrictive, expand as needed

Group Related Permissions

role DataAnalyst {
    permission reports {
        read,
        generate,
        export
    }
    permission analytics {
        read,
        analyze,
        visualize
    }
}

✨ Edit in Studio

Use Standard CRUD Operations
- create, read, update, delete
- Add custom actions when needed

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 {
    "start machine"
    "monitor status"
    "stop machine"
    "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 {
    "review document"
    "approve document"
    "reject document"
}

✨ 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 {
    "create project"
    "assign tasks to members"
    "monitor progress"
    "generate reports"
}

agent SupportAgent: PlatformAdminRole {
    "view user accounts"
    "assist with issues"
    "escalate critical issues"
    "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

Learn about Agents that use roles
Explore Execution Plans
See Complete Examples with roles