# Users & Roles

Helvia gives you fine-grained control over what every team member can access. Permissions operate on three independent layers: workspace roles set Workspace-wide privileges, application roles unlock dedicated tools like LiveChat, and agent-level roles let you configure access per agent. You can invite users, assign roles, and organize teams into groups, all from a single section in Workspace.

Go to **Workspace > Users** to manage your team.

<div data-with-frame="true"><figure><img src="/files/x7MoKfVWp3FXAJs1ljLl" alt=""><figcaption></figcaption></figure></div>

### Understanding the Role System

Permissions in Helvia operate on three independent layers. Each layer controls a different scope of access, and they are configured independently of each other.

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-building-shield">:building-shield:</i></h4><h4>Workspace Access Roles</h4></td><td>Control what a user can see and do across the entire Workspace. Each user gets exactly one role</td><td><a href="/pages/kxnr1ajS9Gjq7Jw7PGFP#workspace-access-roles-1">/pages/kxnr1ajS9Gjq7Jw7PGFP#workspace-access-roles-1</a></td><td><a href="/pages/kxnr1ajS9Gjq7Jw7PGFP#application-roles">/pages/kxnr1ajS9Gjq7Jw7PGFP#application-roles</a></td></tr><tr><td><h4><i class="fa-comments">:comments:</i></h4><h4>Application Roles</h4></td><td>Unlock access to applications like LiveChat as a dedicated application tab</td><td><a href="/pages/kxnr1ajS9Gjq7Jw7PGFP#application-roles-1">/pages/kxnr1ajS9Gjq7Jw7PGFP#application-roles-1</a></td><td></td></tr><tr><td><h4><i class="fa-robot">:robot:</i></h4><h4>Agent-Level Roles</h4></td><td>Set permissions independently for each agent. A user can be an Admin on one agent and a Viewer on another</td><td><a href="/pages/kxnr1ajS9Gjq7Jw7PGFP#agent-level-roles-1">/pages/kxnr1ajS9Gjq7Jw7PGFP#agent-level-roles-1</a></td><td></td></tr></tbody></table>

### Workspace Access Roles

These roles govern what a user can see and do at the Workspace level. Every user is assigned exactly one workspace role, and they are mutually exclusive. A user with **No Workspace access** can only interact with agents they have been explicitly granted access to.

| Capability                      | Viewer | Editor | Admin |
| ------------------------------- | :----: | :----: | :---: |
| View Workspace settings         |    ✅   |    ✅   |   ✅   |
| View Knowledge Bases            |    ✅   |    ✅   |   ✅   |
| Upload new media                |    ✅   |    ✅   |   ✅   |
| View Audit Logs                 |    ❌   |    ✅   |   ✅   |
| Create and edit Knowledge Bases |    ❌   |    ✅   |   ✅   |
| Manage integrations             |    ❌   |    ✅   |   ✅   |
| Delete media                    |    ❌   |    ❌   |   ✅   |
| Invite users                    |    ❌   |    ❌   |   ✅   |
| Manage users and user groups    |    ❌   |    ❌   |   ✅   |
| Change Workspace settings       |    ❌   |    ❌   |   ✅   |

{% hint style="info" %}
Each user can hold exactly one workspace role. You select it when [managing a user](#managing-users) or [sending an invitation](#inviting-new-users).
{% endhint %}

### Application Roles

Application roles unlock access to LiveChat as a separate application alongside Workspace, Designer, and Observatory. Unlike workspace roles, these are additive: a user can hold both, one, or neither. Once assigned, the LiveChat view appears for that user.

| Capability                         | Live Agent | LiveChat Admin |
| ---------------------------------- | :--------: | :------------: |
| Handle live conversations          |      ✅     |        ✅       |
| Configure personal settings        |      ✅     |        ✅       |
| Create and manage canned responses |      ❌     |        ✅       |
| Download transcripts in bulk       |      ❌     |        ✅       |
| Manage global LiveChat settings    |      ❌     |        ✅       |
| Access the Admin Panel             |      ❌     |        ✅       |

For a full walkthrough of the LiveChat application, see [LiveChat](/build/livechat.md).

### Agent-Level Roles

Not every team member needs the same access to every agent. Agent-level roles let you set permissions independently for each agent a user can reach.

| Capability                                | Viewer | Editor | Admin |
| ----------------------------------------- | :----: | :----: | :---: |
| View workflows, settings, and deployments |    ✅   |    ✅   |   ✅   |
| Edit workflows, settings, and deployments |    ❌   |    ✅   |   ✅   |
| Publish agent versions                    |    ❌   |    ✅   |   ✅   |
| Delete workflows or the agent             |    ❌   |    ❌   |   ✅   |
| Manage user access to the agent           |    ❌   |    ❌   |   ✅   |

{% hint style="info" %}
Workspace admins automatically have access to all agents. Users with **No Workspace access** can still access agents they have been explicitly assigned to.
{% endhint %}

### Managing Users

The **Workspace > Users** hub gives you an overview of everyone in your Workspace. From here you can see each user's information like name and email and their access roles. Use the search bar to find a specific user, or select multiple users with the checkboxes to perform bulk actions.

#### Editing a User

{% stepper %}
{% step %}

#### Open the User's Settings

Select any row in the Users table or use the edit action to open the user's settings. The user's name and email are visible at the top but cannot be edited.
{% endstep %}

{% step %}

#### Set the Workspace Role

Assign one of the four workspace roles. This determines the user's permissions across the entire Workspace, from no access to full administrative control.
{% endstep %}

{% step %}

#### Configure Application Roles

Grant or revoke LiveChat access. The two application roles are independent of each other and of the workspace role.
{% endstep %}

{% step %}

#### Manage Agent-Level Access

Choose which agents the user can reach and set a role for each one. You can assign different roles per agent, so a user might be an Editor on one agent and a Viewer on another.
{% endstep %}

{% step %}

#### Assign to User Groups

Add the user to one or more [groups](#user-groups). Any permissions defined at the group level apply automatically.
{% endstep %}

{% step %}

#### Save Changes

Click **Save Changes** to apply the updated permissions.
{% endstep %}
{% endstepper %}

#### Removing a User

To remove a user from your Workspace, open the Users tab and use the delete action <i class="fa-trash-can">:trash-can:</i>. This revokes all access and removes them from any groups they belong to.

{% hint style="danger" %}
Removing a user is permanent. The user will lose access to all agents and Workspace resources immediately.
{% endhint %}

### Inviting New Users

New Workspace members join through email invitations. You configure their initial permissions at the time of invitation, and they complete registration through the link they receive. The invitation link expires after 7 days.

#### Sending an Invitation

{% stepper %}
{% step %}

#### Open the Invitation Form

Go to **Workspace > Users** and click on **Invite New User**.
{% endstep %}

{% step %}

#### Identify the New User

Enter the new user's email. This is the only required field.
{% endstep %}

{% step %}

#### Assign the Workspace Access Role

Assign a workspace role. The default is no access, so change this if the user needs Workspace-level permissions.
{% endstep %}

{% step %}

#### Configure Additional Permissions

Optionally grant LiveChat access and assign agents with per-agent roles. You can also configure these later by editing the user after they accept.
{% endstep %}

{% step %}

#### Send the Invitation

Select **Invite User** to send the invitation email. The invitee can register with a new password.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
The invitation requires at least some level of access. Assign a workspace role, an application role, or agent access before sending.
{% endhint %}

#### Tracking Invitations

The **User Invitations** hub tracks every invitation sent from your Workspace. Here you can see who was invited, what access they were given, whether they accepted, and when the invitation expires.

<div data-with-frame="true"><figure><img src="/files/qn2QU1a2RMXtd6NfdxOH" alt="" width="563"><figcaption></figcaption></figure></div>

Invitations have four possible statuses:

{% tabs %}
{% tab title="Accepted" %}
The user has registered and is now an active member of your team. Their profile appears in the Users tab, where you can edit their permissions.
{% endtab %}

{% tab title="Pending" %}
The invitation has been sent and is waiting for the user to accept. You can revoke a pending invitation using the <i class="fa-arrow-rotate-left">:arrow-rotate-left:</i> action on the row.
{% endtab %}

{% tab title="Revoked" %}
The invitation was manually revoked before the user could accept. Send a new invitation if access is needed again.
{% endtab %}

{% tab title="Expired" %}
The invitation link has passed its expiration date without being used. Send a new invitation if the user still needs access.
{% endtab %}
{% endtabs %}

Filter by status to find pending or expired invitations, or search by email to locate a specific one.

### User Groups

Managing permissions for individual users works well for small teams, but becomes tedious as your team scales. User groups let you bundle users together and assign workspace roles, application roles, and agent access at the group level. When you update a group's permissions, every member inherits the change.

{% hint style="success" %}
Group roles override individual user roles. When a user belongs to a group, the group's roles take effect regardless of what was set on the user directly. If the user is removed from the group, the original roles apply again.
{% endhint %}

<div data-with-frame="true"><figure><img src="/files/CzVWTYAJxFQlPSvoJNt6" alt="" width="563"><figcaption></figcaption></figure></div>

{% stepper %}
{% step %}

#### Create a New Group

Go to **Workspace > User Groups** and click on **Add Group.**
{% endstep %}

{% step %}

#### Name the Group

Choose a name that reflects the team's function, like "Support Team" or "Content Editors"
{% endstep %}

{% step %}

#### Add Members

Select the users who belong to this group. You can add as many members as needed.
{% endstep %}

{% step %}

#### Choose Roles and Agent Access

Assign a workspace role and optional application roles for the group, then choose which agents the group can access with per-agent roles. This works the same way as configuring an individual user.
{% endstep %}

{% step %}

#### Link an External Channel     &#x20;

Optionally link the group to an external platform. This connects the group to teams configured outside of Helvia.
{% endstep %}

{% step %}

#### Save the Group

Select **Create Group** to save. All members immediately inherit the group's permissions.
{% endstep %}
{% endstepper %}

### Best Practices

* **Audit regularly:** Review the Users tab periodically to deactivate accounts that are no longer needed and verify that roles still match responsibilities
* **Separate workspace and agent roles intentionally:** A user can be a Workspace viewer but an agent Admin. Use this to let specialists manage their own agents without touching Workspace settings
* **Set agent access during invitation:** Configuring permissions upfront means the new user can start working immediately after accepting, with no follow-up editing required
* **Name groups descriptively:** "QA Team" or "Tier 2 Support" communicates purpose at a glance. Avoid generic names like "Group 1"

{% hint style="success" %}
You now know how to manage users, configure roles at every level, invite new team members, and organize your team with user groups.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helvia.ai/administration/users-and-roles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.