Skip to main content
Cotool uses Role-Based Access Control (RBAC) to manage what users can do within your organization. Every user is assigned exactly one role, and that role determines their permissions across agents, tools, settings, and more.

​
Definitions

A role is a named collection of permissions that can be assigned to users. Each user in your organization has exactly one role. Examples: “Super Admin”, “Analyst”, “Security Operators”, “Read-Only Users” Roles can be: - System roles (built-in, cannot be modified): Super Admin, Analyst - Custom roles (created by your organization, fully customizable)
A permission grants the ability to perform a specific action on resources. Every permission has two parts: 1. Action: What can be done (e.g., agent.read, tool.use, setting.perms.manage) 2. Resource Scope: Which resources it applies to (all resources or a specific resource) Example: agent.execute with “all” scope = can execute all agents Example: tool.read with specific scope for “jira” = can only read Jira tool configuration
A resource is an entity in Cotool that can be protected by permissions: - Agents (AI workflows) - Tools (integrations like Jira, Splunk, SentinelOne) - Settings (organizational configuration)
  • Insights (dashboards and metrics) - Chats (the chat interface)
An action is the specific operation being performed, following the pattern resource.verb: - agent.read - View agent details - agent.execute - Run an agent - tool.use - Use a tool in agents or chat - setting.perms.manage - Modify roles and permissions
Scope determines which resources a permission applies to: - All scope: Permission applies to all resources of that type - Example: agent.read (all) = read all agents - Specific scope: Permission applies to one specific resource by ID - Example: agent.read (specific: “alert-triage”) = read only the Alert Triage agent Not all permissions support specific scope (e.g., agent.create is always “all”).

​
How RBAC Works

1

Role Creation

Your organization can use built-in system roles (Super Admin, Analyst) or create custom roles with specific permissions. Custom roles let you bundle permissions to match job functions—for example, a “Security Operators” role with access to security agents and specific tools.
2

Role Assignment

Each user in your organization is assigned to exactly one role. Every user must have a role. When you invite or update a user, you choose their role, which immediately determines what they can access.
3

Access Control

When a user attempts any action, Cotool checks their role’s permissions in real-time: Does the role have the required permission? Does it apply to this resource? Are all prerequisite permissions present? If all checks pass, the action proceeds.

​
Permission Categories

Permissions are organized into several categories:
Control access to AI agents:
  • agent.create - Create new agents
  • agent.read - View agent configurations and prior executions
  • agent.execute - Run agents in chat or via triggers
  • agent.edit - Modify existing agents
These can be scoped to all agents or specific agents.
Automatic Permission Sharing: When a user creates an agent, all other users in their role automatically receive agent.read, agent.execute, and agent.edit permissions for that specific agent—even if the role doesn’t have these permissions for “all agents”. This enables team collaboration within roles.
Control access to integrations and tools:
  • tool.read - View tool configurations
  • tool.use - Use tools (required for agents to call them)
  • tool.manage - Connect/disconnect integrations, manage auth
These can be scoped to all tools or specific tool types.
Control chat access:
  • chat.manage - Access the chat interface
Applies to all chats (no specific scoping).
Control alert triage access:
  • alert.triage - Comment on alerts and change alert status
  • alert.manage - Start response-agent triage and manage alert routing Starting response-agent triage also requires agent.execute for the selected response agent. Reading alerts is based on agent.read access to the related origin or triage agents.
Control access to analytics:
  • insight.read - View dashboards and metrics
Applies to all insights (no specific scoping).
Control access to your organization’s platform usage and cost data:
  • billing.read - View platform usage, spend, and invoices, and export usage reports
Applies organization-wide (no specific scoping). Only the Super Admin built-in role has it by default. Add it to a custom role to give access to others, such as a finance contact.
Control access to organizational settings:
  • setting.perms.manage - Create/edit roles and permissions
  • setting.users.invite - Invite new users
  • setting.users.update - Change user roles
  • setting.users.delete - Remove users
  • setting.apiKey.manage - Create/revoke API keys
  • setting.auth.manage - Configure SSO and authentication
  • setting.customModel.manage - Add custom LLM models
  • setting.auditLog.read - View audit logs
All settings permissions apply organization-wide (no specific scoping).

​
Permission Scoping: All vs Specific

Many permissions support two types of scoping:
Grants permission to perform an action on all resources of that type. Example: agent.read with “all” scope means the user can read every agent in the organization. This is simpler to manage and is appropriate when users need broad access.
Not all permissions support specific scoping. For example, agent.create always applies to all agents (you can’t limit someone to “only create agent X”).

​
Built-in Roles

Cotool provides two system roles that cannot be modified:
Full system access - Super Admins can do everything. Permissions include: - All agent permissions (create, read, execute, edit) - All tool permissions (read, use, manage) - All settings permissions (manage users, roles, auth, API keys) - Read insights and audit logs - Manage chats
Every organization must have at least one Super Admin at all times. You cannot delete the last Super Admin or change their role.

​
Critical Rules

One Role Per User - Each user must be assigned to exactly one role. Users cannot have multiple roles or no role.
At Least One Super Admin - Your organization must always have at least one user with the Super Admin role. The system prevents you from removing or demoting the last Super Admin.
Permission Hierarchies - Some permissions require others. For example: - agent.execute requires agent.read - agent.edit requires both agent.read and agent.execute - tool.use requires tool.read - tool.manage requires both tool.read and tool.use

​
Next Steps

Managing Roles

Learn how to create custom roles, assign permissions, and manage users