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

# Roles

> Define permissions and access levels for your team members

## Overview

Roles are the foundation of access control in EasyAlert. Each role contains a set of permissions that determine what actions users can perform. You can use built-in system roles or create custom roles tailored to your organization's needs.

<CardGroup cols={2}>
  <Card title="System Roles" icon="lock">
    Pre-defined roles with standard permission sets that cannot be modified
  </Card>

  <Card title="Custom Roles" icon="lock-open">
    Create your own roles with specific permission combinations
  </Card>
</CardGroup>

***

## Understanding Roles

### Role Types

<Tabs>
  <Tab title="System Roles">
    System roles are pre-configured by EasyAlert and provide standard access patterns.

    **Characteristics:**

    * Cannot be modified or deleted
    * Always available in every organization
    * Marked with a "System" badge
    * Cover common use cases

    **Available System Roles:**

    | Role                | Description                                    |
    | ------------------- | ---------------------------------------------- |
    | **Administrator**   | Full access to all features and settings       |
    | **Incident Admin**  | Full control over incidents including deletion |
    | **Incident Editor** | Create, update, and manage incidents           |
    | **Incident Viewer** | Read-only access to incidents                  |
    | **IAM Admin**       | Manage users, roles, and groups                |
    | **IAM Editor**      | Add and modify users and groups                |
    | **IAM Viewer**      | View users, roles, and group information       |
  </Tab>

  <Tab title="Custom Roles">
    Custom roles allow you to create permission sets specific to your organization.

    **Characteristics:**

    * Fully customizable permissions
    * Can be edited or deleted at any time
    * Marked with a "Custom" badge
    * Scoped to your organization

    **Use Cases:**

    * Department-specific access (e.g., "Support Team Lead")
    * Project-based permissions
    * Compliance requirements
    * Temporary elevated access
  </Tab>
</Tabs>

### Role Scope

<CardGroup cols={2}>
  <Card title="Tenant Scope" icon="building">
    Permissions apply within your organization only. Most roles use this scope.
  </Card>

  <Card title="Platform Scope" icon="globe">
    Platform-wide permissions for EasyAlert administrators. Rarely used.
  </Card>
</CardGroup>

***

## Viewing Roles

The Roles page displays all available roles with key information:

| Column          | Description                                   |
| --------------- | --------------------------------------------- |
| **Role**        | Role name and unique key identifier           |
| **Description** | Brief explanation of the role's purpose       |
| **Scope**       | Whether the role is tenant or platform scoped |
| **Type**        | System (locked) or Custom (editable)          |
| **Actions**     | View permissions, edit, or delete             |

### Viewing Role Permissions

To see what permissions a role grants:

1. Find the role in the list
2. Click the **three-dot menu** (⋮)
3. Select **View Permissions**

The dialog shows all permissions organized by category, making it easy to understand what access the role provides.

<Tip>
  Wildcard permissions (like `incidents:*:*`) are highlighted with an amber
  indicator, showing they grant broad access to an entire category.
</Tip>

***

## Creating Custom Roles

<Steps>
  <Step title="Open Create Dialog">
    Click the **Create Role** button in the top right corner
  </Step>

  <Step title="Define Role Identity">
    Enter the role details: - **Role Key** — Unique identifier (lowercase,
    underscores allowed, e.g., `support_lead`) - **Role Name** — Display name
    (e.g., "Support Team Lead") - **Description** — Explain the role's purpose
  </Step>

  <Step title="Select Permissions">
    Choose the permissions this role should have: - Use the search bar to filter
    permissions - Permissions are grouped by category - Check the boxes next to
    desired permissions - The badge shows how many permissions are selected
  </Step>

  <Step title="Save the Role">Click **Create** to save your new role</Step>
</Steps>

<Warning>
  The Role Key cannot be changed after creation. Choose a meaningful, permanent
  identifier.
</Warning>

***

## Understanding Permissions

Permissions control specific actions within the platform. They follow a structured format:

```
service:resource:action
```

### Permission Categories

<AccordionGroup>
  <Accordion title="Incidents">
    Control access to incident management features.

    | Permission             | Description                      |
    | ---------------------- | -------------------------------- |
    | `incident:read`        | View incidents and their details |
    | `incident:write`       | Create and update incidents      |
    | `incident:delete`      | Delete incidents                 |
    | `incident:acknowledge` | Acknowledge incident alerts      |
    | `incident:resolve`     | Mark incidents as resolved       |
  </Accordion>

  <Accordion title="Users & Access (IAM)">
    Control access to user and access management.

    | Permission     | Description                  |
    | -------------- | ---------------------------- |
    | `user:read`    | View user information        |
    | `user:write`   | Add and edit users           |
    | `user:delete`  | Remove users                 |
    | `role:read`    | View roles and permissions   |
    | `role:write`   | Create and edit custom roles |
    | `role:delete`  | Delete custom roles          |
    | `group:read`   | View groups and members      |
    | `group:write`  | Manage groups and membership |
    | `group:delete` | Delete groups                |
  </Accordion>

  <Accordion title="Schedules & On-Call">
    Control access to scheduling features.

    | Permission        | Description                 |
    | ----------------- | --------------------------- |
    | `schedule:read`   | View on-call schedules      |
    | `schedule:write`  | Create and modify schedules |
    | `schedule:delete` | Delete schedules            |
  </Accordion>

  <Accordion title="Integrations">
    Control access to third-party integrations.

    | Permission           | Description                    |
    | -------------------- | ------------------------------ |
    | `integration:read`   | View configured integrations   |
    | `integration:write`  | Add and configure integrations |
    | `integration:delete` | Remove integrations            |
  </Accordion>
</AccordionGroup>

### Wildcard Permissions

Wildcards allow granting broad access without selecting individual permissions:

| Pattern      | Meaning                   |
| ------------ | ------------------------- |
| `incident:*` | All incident permissions  |
| `*:read`     | Read access to everything |
| `*:*`        | Full access to everything |

<Info>
  Use wildcards carefully. They grant extensive access and should only be
  assigned to trusted roles.
</Info>

***

## Editing Custom Roles

To modify an existing custom role:

<Steps>
  <Step title="Find the Role">
    Locate the custom role in the list (look for the "Custom" badge)
  </Step>

  <Step title="Open Edit Dialog">
    Click the **three-dot menu** (⋮) and select **Edit**
  </Step>

  <Step title="Make Changes">
    Update the role name, description, or permissions as needed
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to apply your modifications
  </Step>
</Steps>

<Note>
  System roles cannot be edited. If you need different permissions, create a
  custom role instead.
</Note>

***

## Deleting Custom Roles

Before deleting a role, ensure no users or groups are using it.

<Steps>
  <Step title="Check Usage">
    Review which users and groups have this role assigned
  </Step>

  <Step title="Remove Assignments">
    Reassign users and groups to different roles if needed
  </Step>

  <Step title="Delete the Role">
    Click the **three-dot menu** (⋮) and select **Delete**
  </Step>

  <Step title="Confirm Deletion">
    Click **Delete** in the confirmation dialog
  </Step>
</Steps>

<Warning>
  If the role is still assigned to users or groups, you'll see an error message
  listing the assignments that need to be removed first.
</Warning>

***

## Assigning Roles

Roles can be assigned in two ways:

### Direct Assignment

Assign roles directly to individual users:

1. Go to **Settings** → **Users**
2. Edit the user's profile
3. Select the roles in the **Roles** section
4. Save changes

### Group Assignment

Assign roles to groups for bulk access control:

1. Go to **Settings** → **Groups**
2. Edit the group or create a new one
3. Select the roles to assign
4. All group members automatically inherit these roles

<Tip>
  Group-based role assignment is recommended for teams. When someone joins the
  group, they automatically get the right permissions.
</Tip>

***

## How Permissions Work Together

When a user has multiple roles (directly or through groups), their effective permissions are the **union** of all role permissions.

<Accordion title="Example: Combined Permissions">
  **User: Sarah**

  Direct Roles:

  * Incident Viewer (`incident:read`)

  Group Membership:

  * Engineering Team → Incident Editor (`incident:read`, `incident:write`)

  **Effective Permissions:**

  * `incident:read` ✓
  * `incident:write` ✓

  Sarah can both view AND edit incidents because her permissions combine.
</Accordion>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Follow Least Privilege">
    Give users only the permissions they need. Start with minimal access and add
    permissions as required rather than starting with full access and
    restricting.
  </Accordion>

  <Accordion title="Use Groups for Team Access">
    Instead of assigning roles to each user individually, create groups for
    teams and assign roles to the group. This makes onboarding and offboarding
    much easier.
  </Accordion>

  <Accordion title="Create Meaningful Role Names">
    Use descriptive names that indicate the role's purpose, like "Support Team
    Lead" rather than "Role 1". Include the team or function in the name.
  </Accordion>

  <Accordion title="Document Custom Roles">
    Use the description field to explain why the role was created and what it's
    intended for. This helps future administrators understand the access model.
  </Accordion>

  <Accordion title="Review Roles Periodically">
    Audit your custom roles regularly. Remove unused roles and verify that
    permission assignments still match your organization's needs.
  </Accordion>

  <Accordion title="Avoid Wildcard Overuse">
    Wildcard permissions are convenient but can grant more access than intended.
    Use specific permissions when possible.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="User can't access a feature they should have">
    1. Check if the user has the correct role assigned 2. Verify the role
       includes the necessary permission 3. Check if the user is in a group with
       the role 4. Ensure the user's account is active
  </Accordion>

  <Accordion title="Can't edit or delete a role">
    System roles cannot be modified. Look for the "System" badge next to the
    role. If you need different permissions, create a new custom role.
  </Accordion>

  <Accordion title="Can't delete a custom role">
    The role is still assigned to users or groups. Remove all assignments first,
    then try deleting again. The error message will list which users/groups need
    to be updated.
  </Accordion>

  <Accordion title="Permission changes aren't taking effect">
    Users may need to refresh their session. Ask them to log out and back in to
    pick up the new permissions.
  </Accordion>
</AccordionGroup>