> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles & Permissions Overview

> Understanding role-based access control in Cotool

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

<AccordionGroup>
  <Accordion title="Role" icon="users">
    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)
  </Accordion>

  <Accordion title="Permission" icon="lock">
    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
  </Accordion>

  <Accordion title="Resource" icon="cube">
    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)
  </Accordion>

  <Accordion title="Action" icon="bolt">
    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
  </Accordion>

  <Accordion title="Scope" icon="bullseye">
    **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").
  </Accordion>
</AccordionGroup>

## How RBAC Works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Permission Categories

Permissions are organized into several categories:

<AccordionGroup>
  <Accordion title="Agent Permissions" icon="wand-magic-sparkles">
    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.

    <Info>
      **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.
    </Info>
  </Accordion>

  <Accordion title="Tool Permissions" icon="wrench">
    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.
  </Accordion>

  <Accordion title="Chat Permissions" icon="messages">
    Control chat access:

    * **chat.manage** - Access the chat interface

    Applies to all chats (no specific scoping).
  </Accordion>

  <Accordion title="Alert Permissions" icon="bell">
    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.
  </Accordion>

  <Accordion title="Insight Permissions" icon="chart-simple">
    Control access to analytics:

    * **insight.read** - View dashboards and metrics

    Applies to all insights (no specific scoping).
  </Accordion>

  <Accordion title="Settings Permissions" icon="gear">
    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).
  </Accordion>
</AccordionGroup>

## Permission Scoping: All vs Specific

Many permissions support two types of scoping:

<Tabs>
  <Tab title="All Scope">
    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.
  </Tab>

  <Tab title="Specific Scope">
    Grants permission to perform an action on **one specific** resource.

    **Example**: `agent.execute` with specific scope for agent ID "abc-123" means the user can only execute that one agent.

    Use this for fine-grained access control when you want to limit users to specific agents or tools.
  </Tab>
</Tabs>

<Note>
  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").
</Note>

## Built-in Roles

Cotool provides two system roles that cannot be modified:

<Tabs>
  <Tab title="Super Admin">
    **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

    <Warning>
      Every organization **must have at least one Super Admin** at all times. You cannot delete the last Super Admin or change their role.
    </Warning>
  </Tab>

  <Tab title="Analyst">
    **Read and execute agents and tools** - Analysts can use Cotool but cannot modify configuration.

    **Permissions include:**

    * Read, execute, and edit agents
    * Read and use tools
    * Read insights
    * Manage chats

    **Cannot do:**

    * Create new agents
    * Manage tool configurations
    * Modify settings (users, roles, integrations)
    * Read audit logs
  </Tab>
</Tabs>

## Critical Rules

<Warning>
  **One Role Per User** - Each user must be assigned to exactly one role. Users cannot have multiple roles or no role.
</Warning>

<Warning>
  **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.
</Warning>

<Warning>
  **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`
</Warning>

## Next Steps

<Card title="Managing Roles" href="/settings/managing-roles" icon="users-gear">
  Learn how to create custom roles, assign permissions, and manage users
</Card>