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

# Role management

> Create roles, share roles with managed tenants, and choose permissions

## How roles work

Roles group permissions into reusable access profiles. Assign roles to users to control what they can see and change in Maadify.

Each permission uses this format:

```text theme={null}
resource.action
```

For example, `connectors.read` lets a user view configured connectors, while `connectors.update` lets a user update connector settings.

<Tip>
  Start with read and access permissions. Add create, update, delete, execute, and share permissions only when the user needs those actions.
</Tip>

## System roles

System roles provide common access profiles that you can assign without building a custom role. You can copy a system role when you need a custom version.

<AccordionGroup>
  <Accordion title="owner">
    Full access to all resources.
  </Accordion>

  <Accordion title="admin">
    Manage roles and assign them to internal users in your tenant. This role is for non-owned tenant users.
  </Accordion>

  <Accordion title="chat_only">
    Access only the chat interface. This role does not provide admin portal access.
  </Accordion>

  <Accordion title="viewer">
    View access to all resources.
  </Accordion>

  <Accordion title="user_manager">
    Manage internal users. This includes adding users, updating users, removing users, and assigning roles.
  </Accordion>

  <Accordion title="tenant_manager">
    Manage tenants and their users. This includes creating, updating, and deleting tenants.
  </Accordion>

  <Accordion title="agent_manager">
    Manage agent creation. This includes creating and updating parent agents, sub-agents, prompt templates, assigning existing tools to agents, and assigning parent agents to tenants.
  </Accordion>

  <Accordion title="connector_manager">
    Manage connectors and tool configuration. Use this role to set up systems and make tools available for agents.
  </Accordion>

  <Accordion title="monitor_agents">
    Manage agent activity and receive notifications.
  </Accordion>

  <Accordion title="notifications">
    Receive notifications from all users in your tenant and owned tenants.
  </Accordion>

  <Accordion title="index_store_manager">
    Manage Index Data Store configurations and setup.
  </Accordion>
</AccordionGroup>

<Info>
  System roles are global roles. They are not tenant-owned custom roles and cannot be shared to managed tenants.
</Info>

<Frame>
  <img src="https://mintcdn.com/maadify/X4aEKWAIWIr8YAhZ/images/users/role_management.png?fit=max&auto=format&n=X4aEKWAIWIr8YAhZ&q=85&s=89cae0e1a2b9bbf3358898d863440d9f" alt="Manage Roles list showing role names, descriptions, System badges, and Shared badges" width="1611" height="800" data-path="images/users/role_management.png" />
</Frame>

## Create a role

<Steps>
  <Step title="Open role management">
    Go to **Users** and select **Manage Roles**.
  </Step>

  <Step title="Create the role">
    Select **Create Role**, then enter a role name and description.
  </Step>

  <Step title="Choose whether to share the role">
    Turn on **Shared Role** if users in owned tenants should be able to use this role.
  </Step>

  <Step title="Add permissions">
    Search permissions by resource, action, or description. Add each permission the role needs.
  </Step>

  <Step title="Save the role">
    Select **Create Role**.

    <Check>
      The role appears in the role list and can be assigned to users.
    </Check>
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/maadify/X4aEKWAIWIr8YAhZ/images/users/add_edit_role.png?fit=max&auto=format&n=X4aEKWAIWIr8YAhZ&q=85&s=521386802a25b445584246c2b6ba0c06" alt="Create Role dialog showing role fields, Shared Role switch, assigned permissions, and available permissions" width="945" height="895" data-path="images/users/add_edit_role.png" />
</Frame>

## Copy a role

You can copy an existing role when you want to start from a system role or a similar custom role.

<Steps>
  <Step title="Open a role">
    Select the role from **Manage Roles**.
  </Step>

  <Step title="Enable copy mode">
    Turn on **Copy Role**.
  </Step>

  <Step title="Name the copied role">
    Enter a new role name and description.
  </Step>

  <Step title="Choose sharing">
    Turn on **Copy Role Shared** if the copied role should be available to owned tenants.
  </Step>

  <Step title="Create the copy">
    Select **Copy Role**.
  </Step>
</Steps>

<Info>
  System roles cannot be edited directly. Copy a system role when you need a custom version.
</Info>

## Share roles with managed tenants

Enable **Shared Role** when an owning tenant should make a custom role available to its owned tenants.

Shared roles are used when assigning roles to managed company users:

* Users in your own tenant can be assigned roles from your tenant.
* Users in owned or managed tenants can be assigned non-system roles that your tenant has shared.
* Shared roles help standardize access for managed companies.

<Warning>
  Sharing a role makes it available for assignment. It does not automatically assign the role to any user.
</Warning>

## Required permissions

You need role permissions to manage roles:

* `roles.read`: View roles and open **Manage Roles**.
* `roles.create`: Create roles and copy existing roles.
* `roles.update`: Update custom roles.
* `roles.delete`: Delete custom roles.

You also need user management permissions to assign roles to users:

* `users.update`: Assign roles to users in your own tenant.
* `tenant_users.update`: Assign roles to users in owned or managed tenants.

## Permission catalog

Use these permissions to build roles.

<AccordionGroup>
  <Accordion title="Admin portal">
    * `admin_portal.access`: Access the admin portal. Without this permission, the user only has access to the chat interface.
  </Accordion>

  <Accordion title="Users and tenant users">
    * `users.read`: View users in your own tenant.
    * `users.create`: Create users in your own tenant.
    * `users.update`: Update users and assign roles in your own tenant.
    * `users.delete`: Delete users in your own tenant.
    * `tenant_users.read`: View users in owned or managed tenants.
    * `tenant_users.create`: Create users in owned or managed tenants.
    * `tenant_users.update`: Update users and assign shared roles in owned or managed tenants.
    * `tenant_users.delete`: Delete users in owned or managed tenants.
  </Accordion>

  <Accordion title="Roles">
    * `roles.read`: View roles.
    * `roles.create`: Create custom roles.
    * `roles.update`: Update roles.
    * `roles.delete`: Delete roles.
  </Accordion>

  <Accordion title="Companies and tenant relationships">
    * `tenants.read`: View the companies page. Connected tenants can still be visible for agent use.
    * `tenants.create`: Create new owned tenants. Users in owned tenants cannot create tenants.
    * `tenants.update`: Update existing tenants and create relationships. Users can create relationships from owned tenants, such as adding a supplier relationship for an existing channel.
    * `tenants.delete`: Deactivate owned tenants.
    * `tenant_agent_relationships.read`: View agent and tool configurations for tenant relationships.
    * `tenant_agent_relationships.create`: Add agents to owned tenant relationships.
    * `tenant_agent_relationships.update`: Update agent relationship configurations, including tool configurations.
    * `tenant_agent_relationships.delete`: Remove parent agents from tenants.
  </Accordion>

  <Accordion title="Connectors and tools">
    * `connectors.read`: View configured connectors.
    * `connectors.create`: Add new connectors.
    * `connectors.update`: Update connector settings.
    * `connectors.delete`: Delete connector settings.
    * `tools.read`: View tool configurations on the connectors page.
    * `tools.create`: Create tools and configure default configurations for agents.
    * `tools.update`: Update tools, update default configurations, and add or remove orphaned tools from connections.
    * `tools.delete`: Delete tools on connector configurations.
    * `tools.share`: Share and unshare tools to connected tenants.
    * `tools.execute`: Execute tools through the API.
  </Accordion>

  <Accordion title="Parent agents and triggers">
    * `parent_agents.read`: View parent agent configurations and show the parent agents section in the portal.
    * `parent_agents.create`: Create parent agents. Add `parent_agents.update` to configure parent agents with sub-agents.
    * `parent_agents.update`: Update parent agents, including adding or removing existing sub-agents.
    * `parent_agents.delete`: Delete parent agents.
    * `trigger_tools.read`: View trigger tool configurations.
    * `trigger_tools.create`: Create triggers on parent agents.
    * `trigger_tools.update`: Update existing triggers on parent agents.
    * `trigger_tools.delete`: Remove triggers from parent agents.
  </Accordion>

  <Accordion title="Sub-agents">
    * `sub_agents.read`: View the sub-agents page.
    * `sub_agents.create`: Create sub-agents. This does not provide access to add sub-agents to parent agents.
    * `sub_agents.update`: Update existing sub-agents, including system prompts, model changes, and adding or removing existing tools. Changes can affect parent agents.
    * `sub_agents.delete`: Delete sub-agents. Deleting a sub-agent can affect parent agents.
  </Accordion>

  <Accordion title="Prompt templates">
    * `prompt_templates.read`: Access the prompt templates page.
    * `prompt_templates.create`: Create prompt templates.
    * `prompt_templates.update`: Update prompt templates. Changes can affect sub-agent configurations that use the template.
    * `prompt_templates.delete`: Delete prompt templates. Deletions can affect sub-agent configurations that use the template.
  </Accordion>

  <Accordion title="Browser agent">
    * `browser_agent.access`: Create and edit browser agent tools. Users also need the required tool permissions for the tools they configure.
  </Accordion>

  <Accordion title="Agent activity">
    * `agent_activity.access`: View the tenant and shared tenant agent activity page.
    * `agent_activity.read`: View activity across all users in the tenant, including trigger executions.
  </Accordion>

  <Accordion title="Index data store">
    * `index_data_store.access`: Access the Index Data Store page.
    * `index_data_store.read`: Read and search data in tenant-owned data stores.
    * `index_data_store.create`: Create rows of data and execute index data automations.
    * `index_data_store.delete`: Delete rows in tenant-owned data stores.
    * `index_data_store_config.read`: View Index Data Store configurations.
    * `index_data_store_config.create`: Configure new data stores.
    * `index_data_store_config.update`: Update data store configurations.
    * `index_data_store_config.delete`: Remove configured data stores.
  </Accordion>

  <Accordion title="Notifications">
    * `notifications.receive_owned_tenant`: Receive notifications associated with owned tenants, including configured errors, warnings, and notices.
    * `notifications.receive_errors`: Receive tenant-level errors.
    * `notifications.receive_warnings`: Receive tenant-level warnings.
    * `notifications.receive_notice`: Receive tenant-level notices.
  </Accordion>

  <Accordion title="Chat and search">
    * `universal_search.access`: Use the universal search agent to search data in index data stores.
  </Accordion>
</AccordionGroup>

## Suggested role patterns

Use these patterns as starting points:

* **Portal viewer**: `admin_portal.access` plus read permissions for the pages the user needs.
* **User administrator**: `admin_portal.access`, `users.*`, and `roles.read`.
* **Managed company administrator**: `admin_portal.access`, `tenant_users.*`, and `roles.read`.
* **Role administrator**: `admin_portal.access`, `roles.*`, `users.update`, and `tenant_users.update` when they should assign roles.
* **Agent builder**: parent agent, sub-agent, prompt template, trigger, connector read, and tool read or update permissions.
* **Data operator**: index data store access, read, create, and the required universal search permission.