Users and roles

Manage the people in a workspace under Manage > Users, and what they can do under Manage > Roles. Access is per workspace: someone who belongs to two workspaces can have a different role in each.

Inviting, changing roles, deactivating, removing and resetting passwords require the workspace admin role. A custom role that includes users.manage can edit roles, but it can’t manage members.

Inviting someone

There is no self-service sign-up. People join a workspace by invitation, or through single sign-on.

1. Open Users and select Invite User.
2. Enter their Email and Name, and pick a Role.
3. Leave Send invitation email (if configured) ticked to email the link, and select Send Invite.
4. If the email can’t be sent, the dialog says Email not sent. Copy the link and share it manually. Select Copy Link and send it yourself.

The person opens the link, enters their full name and a password of at least 8 characters, and selects Accept Invitation. If they already have a VirtuAI account, they keep their existing password and are added to the workspace.

Invitation links expire after 48 hours and work once. Inviting the same email again replaces the earlier link.

Pending invitations

Pending Invitations, on the Users page, lists invitations nobody has accepted yet, with the date they were sent and the date they expire.

• Resend link creates a new link, invalidates the old one and copies the new one.
• Revoke invitation cancels the link.

When someone reports that a link doesn’t work, the page they see tells you why: the link is incomplete, invalid or revoked, expired, or already used. For all of these, send a new invitation.

Managing members

Each member row has these actions:

Action	What it does
Change Role	Assigns a different role. Takes effect on their next request.
Reset Password	Sets a new password for them, of at least 8 characters. Use it when someone forgets theirs: there’s no self-service reset.
Deactivate / Activate	Suspends or restores their access to this workspace without removing them. They keep access to their other workspaces.
Remove from Workspace	Removes their membership. The workspace owner can’t be removed.

Note

For people who sign in with SSO, manage access in your identity provider. Each SSO sign-in sets their role from their groups and reactivates their membership, so a change made only in VirtuAI is undone the next time they sign in.

Default roles

Every workspace starts with three roles:

Role	For	Can
admin	Workspace administrators	Everything in the workspace: settings and keys, members and roles, publishing and deleting agents, reading any transcript, revealing masked data, budgets, and the Agent Builder
user	People who build and run agents	Create and edit agents, tools and knowledge bases, see the conversation list, dashboards and budgets, and run evaluations. Can’t publish or delete agents, or read other people’s transcripts.
viewer	Stakeholders who only watch	Read-only access to agents, tools, knowledge bases, the conversation list, dashboards and evaluations

There is also webapp_viewer, a chat-only role with no access to the admin console. Use it for people who should only talk to agents in the workspace web chat.

See the Permissions reference for exactly which permissions each role has.

Custom roles

Create a role when the defaults don’t fit, for example someone who can build agents but not see conversations, or a reviewer who can read transcripts but not reveal masked data.

1. Open Roles and select Create Role.
2. Enter a Name and, optionally, a Description.
3. Tick the permissions the role should have. They’re grouped by area: agents, tools, conversations and so on.
4. Select Create Role. It’s now available in Invite User and Change Role.

Edit or delete a custom role from its card. You can’t delete a role while anyone has it: assign those people another role first. Roles marked System are platform templates and can’t be edited or deleted.

Caution

To restrict access, create a custom role instead of removing permissions from admin, user or viewer. When VirtuAI adds a permission to a default role, it is added to every workspace’s copy of that role, and a permission you removed can come back.

Creating, editing and deleting roles requires users.manage.

Single sign-on

Connect your identity provider so people sign in with their company account. Any OpenID Connect provider works, Keycloak included. If you use Azure AD or LDAP, federate them in your identity provider; VirtuAI connects to one OIDC issuer per workspace.

Configure it in Settings > Identity Provider (SSO). This requires settings.manage.

1. In your identity provider, create a confidential OIDC client. Set its redirect URI to https://app.imvirtuai.com/api/auth/sso/callback, and include a groups claim in the ID token.

2. In VirtuAI, fill in:

   Field	Value
   Issuer URL	Your issuer, for example https://sso.example.com/realms/acme
   Client ID and Client secret	From the client you created. The secret is encrypted, and shows (unchanged) once saved.
   Allowed email domains	Comma-separated, for example acme.com, acme.co. Only these domains can sign in, and they’re what routes a work email to your workspace.
   Group claim	The claim that carries groups. Default: groups.
   Role mappings	JSON mapping each group to a workspace role, for example {"virtuai-admins": "admin", "virtuai-users": "user"}
   Default role	The role for people in none of the mapped groups. Leave it empty to deny them.

3. Choose whether to enable JIT provisioning on first login. With it on, VirtuAI creates the account the first time someone signs in. With it off, only people who already have an account can sign in.

4. Select Test connection to check that VirtuAI can read your issuer’s configuration, then tick Enable SSO for this workspace and Save.

People then select Sign in with SSO on the sign-in page and enter their work email.

• A group mapping can grant any workspace role, including admin, but never platform administrator access.
• If someone matches no mapping and there’s no default role, sign-in is refused.
• A VirtuAI session ends when the ID token from your identity provider expires, and at most after 24 hours. Signing out of VirtuAI also signs them out of the identity provider, and VirtuAI accepts back-channel logout, so ending a session in the identity provider ends it in VirtuAI.

Platform administrators

Platform administrators operate the VirtuAI service itself. In any workspace they belong to, they pass every permission check. They create workspaces and are the only people who see Workspaces and Logs in the menu and the super-admin control on Users. Workspace admins can’t grant this access, and SSO can’t either.

Recommendations

• Give admin only to trusted operators. It can read every transcript and reveal masked customer data.
• Give each person the smallest role that lets them do their job, and use custom roles for anything in between.
• Keep agents.publish for the people who approve what reaches customers.
• Review the member list when people change teams or leave. With SSO, remove them in your identity provider.