Roles

What is a Role?

A role is a named collection of permissions. Instead of assigning individual permissions to each subject, you create roles like “Editor” or “Admin” and assign those roles to subjects via their memberships.

Role Properties

Property	Type	Description
`id`	`string`	Unique identifier
`name`	`string`	Human-readable name (e.g., “Editor”, “Admin”)
`description`	`string?`	What this role is for
`scopeId`	`string`	The scope where this role is defined

Creating Roles

Roles are defined at a specific scope and can be assigned to memberships in that scope and any of its descendants (assignment is explicit—it does not propagate access automatically):

# Create an Editor role at the organization level
curl -X POST 'https://api.example.com/roles' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Editor",
    "description": "Can read and write documents",
    "scopeId": "scope_acme"
  }'

Role Permissions

A role is just a container—it has no permissions until you add them. Use role permissions to connect roles to permissions:

# First, create permissions
curl -X POST 'https://api.example.com/permissions/batch' \
  -d '[
    {"id": "perm_read", "scopeId": "scope_acme", "action": "read", "resourceType": "document", "resourcePattern": "*", "key": "document:read:*"},
    {"id": "perm_write", "scopeId": "scope_acme", "action": "write", "resourceType": "document", "resourcePattern": "*", "key": "document:write:*"}
  ]'

# Then, add permissions to the role
curl -X POST 'https://api.example.com/role-permissions/batch' \
  -d '[
    {"roleId": "role_editor", "permissionId": "perm_read"},
    {"roleId": "role_editor", "permissionId": "perm_write"}
  ]'

Role Assignments

To grant a role to a subject, create a role assignment that links the role to a membership:

# Subject must have a membership first
curl -X POST 'https://api.example.com/memberships' \
  -d '{"id": "membership_jane", "subjectId": "subject_jane", "scopeId": "scope_engineering"}'

# Then assign the role to the membership
curl -X POST 'https://api.example.com/role-assignments' \
  -d '{"roleId": "role_editor", "membershipId": "membership_jane"}'

Reusing Roles Across Scopes

A role definition created at a parent scope can be assigned at any child scope—you don’t have to redefine it per scope:

Organization (defines: Admin, Editor, Viewer)
    │
    ├── Team A ─── can assign Admin, Editor, Viewer
    │   │
    │   └── Project X ─── can assign Admin, Editor, Viewer
    │
    └── Team B ─── can assign Admin, Editor, Viewer

This is about role availability for assignment, not automatic grants. Under the default override mode, a subject with an “Editor” membership at the Organization scope does not automatically have Editor permissions in Team A or Project X—memberships are evaluated at the exact scope of the request, so you create a membership (and role assignment) at each scope where access is needed. Scope types configured as inherit or additive do compose grants from ancestors. See Scope Types, Scopes, and Evaluation.

Scope-Specific Roles

You can also define roles at child scopes for more specific use cases:

# Organization-wide roles
curl -X POST 'https://api.example.com/roles' \
  -d '{"name": "Editor", "scopeId": "scope_acme"}'

# Team-specific role
curl -X POST 'https://api.example.com/roles' \
  -d '{"name": "Sprint Manager", "scopeId": "scope_engineering"}'

# Project-specific role
curl -X POST 'https://api.example.com/roles' \
  -d '{"name": "Release Approver", "scopeId": "scope_backend"}'

Common Role Patterns

Standard RBAC Roles

curl -X POST 'https://api.example.com/roles/batch' \
  -d '[
    {"name": "Admin", "description": "Full access", "scopeId": "scope_org"},
    {"name": "Editor", "description": "Read and write", "scopeId": "scope_org"},
    {"name": "Viewer", "description": "Read only", "scopeId": "scope_org"}
  ]'

Agent-Specific Roles

curl -X POST 'https://api.example.com/roles/batch' \
  -d '[
    {"name": "Agent Reader", "description": "AI agent with read access", "scopeId": "scope_org"},
    {"name": "Agent Writer", "description": "AI agent with write access", "scopeId": "scope_org"},
    {"name": "Agent Executor", "description": "AI agent that can execute code", "scopeId": "scope_org"}
  ]'

Functional Roles

curl -X POST 'https://api.example.com/roles/batch' \
  -d '[
    {"name": "Billing Manager", "description": "Manage billing and invoices", "scopeId": "scope_org"},
    {"name": "User Manager", "description": "Manage team members", "scopeId": "scope_org"},
    {"name": "Auditor", "description": "View audit logs", "scopeId": "scope_org"}
  ]'

Role Overrides

You can disable a role at a child scope using role overrides:

# Deactivate the Admin role in production
curl -X POST 'https://api.example.com/scope-overrides/roles' \
  -d '{
    "childScopeId": "scope_production",
    "roleId": "role_admin",
    "state": "inactive"
  }'

Now the Admin role grants nothing in Production—any subject who holds it there loses its permissions at that scope. (Valid role-override states are active, inactive, and inherit.)

Learn about Overrides

See all override types and patterns

Multiple Roles per Membership

A membership can have multiple roles:

# Jane has both Editor and Billing Manager roles
curl -X POST 'https://api.example.com/role-assignments/batch' \
  -d '[
    {"roleId": "role_editor", "membershipId": "membership_jane"},
    {"roleId": "role_billing_manager", "membershipId": "membership_jane"}
  ]'

The subject’s effective permissions are the union of all their roles’ permissions.

Viewing Role Permissions

# Get all permissions for a role
curl -X GET 'https://api.example.com/role-permissions?roleId=role_editor'

Viewing Role Assignments

# Get all role assignments for a membership
curl -X GET 'https://api.example.com/role-assignments?membershipId=membership_jane'

# Get all role assignments for a role
curl -X GET 'https://api.example.com/role-assignments?roleId=role_editor'

Best Practices

Keep roles focused

Create roles for specific purposes rather than catch-all roles. “Billing Manager” is better than “Manager”.

Define roles at the right level

Organization-wide roles at the org level, team-specific roles at the team level.

Use descriptive names

“Document Editor” is clearer than “Editor” if you have multiple resource types.

Document role purposes

Use the description field to explain what each role is for.

Prefer roles over direct permissions

Always assign permissions via roles, not directly to subjects.

API Reference

Create Role

Create a new role

Create Role Permission

Add a permission to a role

Create Role Assignment

Assign a role to a membership

Get Roles by Scope

List roles in a scope

Next Steps

Permissions

Learn how permissions define specific access rights

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

What is a Role?

Role Properties

Creating Roles

Role Permissions

Role Assignments

Reusing Roles Across Scopes

Scope-Specific Roles

Common Role Patterns

Standard RBAC Roles

Agent-Specific Roles

Functional Roles

Role Overrides

Learn about Overrides

Multiple Roles per Membership

Viewing Role Permissions

Viewing Role Assignments

Best Practices

API Reference

Create Role

Create Role Permission

Create Role Assignment

Get Roles by Scope

Next Steps

Permissions

​What is a Role?

​Role Properties

​Creating Roles

​Role Permissions

​Role Assignments

​Reusing Roles Across Scopes

​Scope-Specific Roles

​Common Role Patterns

​Standard RBAC Roles

​Agent-Specific Roles

​Functional Roles

​Role Overrides

Learn about Overrides

​Multiple Roles per Membership

​Viewing Role Permissions

​Viewing Role Assignments

​Best Practices

​API Reference

Create Role

Create Role Permission

Create Role Assignment

Get Roles by Scope

​Next Steps

Permissions

What is a Role?

Role Properties

Creating Roles

Role Permissions

Role Assignments

Reusing Roles Across Scopes

Scope-Specific Roles

Common Role Patterns

Standard RBAC Roles

Agent-Specific Roles

Functional Roles

Role Overrides

Multiple Roles per Membership

Viewing Role Permissions

Viewing Role Assignments

Best Practices

API Reference

Next Steps