# Roles and permissions

Decide what each person can see and do in your organization and on each AI Team, with system roles on every plan and custom roles on Professional and Enterprise.



Every person in your organization has a role. A role is a set of permissions, such as "See
billing", "Start sessions" or "Reveal team secret values". HQ checks the permission on every
request, so a person can only do what their role allows.

## Where roles live [#where-roles-live]

Roles are a tab of **People**: **Members** lists the people in your organization, and **Roles** lists
the system and custom roles. You see the **Roles** tab if your role lets you see roles. Roles used to
be under **Settings**; old links to them still work.

## System roles [#system-roles]

Six roles come with every organization. They can't be changed.

| Role       | Applies to   | What it allows                              |
| ---------- | ------------ | ------------------------------------------- |
| Owner      | Organization | Everything, including billing and ownership |
| Admin      | Organization | Everything except ownership and roles       |
| Member     | Organization | Sees the AI Teams they are added to         |
| Team owner | AI Team      | Runs the AI Team, its secrets and access    |
| Editor     | AI Team      | Works in sessions, files and schedules      |
| Viewer     | AI Team      | Watches sessions and reads files            |

An organization owner or admin is a team owner on every AI Team. To see exactly what a system role
allows, open **People**, then the **Roles** tab, and select the role. On **People**, a person's role
also links to that role's page.

## Custom roles [#custom-roles]

On Professional and Enterprise, an organization owner can create custom roles. Professional
includes 25 custom roles; Enterprise has no limit. Custom roles are not available during a trial.

A custom role applies either to the **organization** or to an **AI Team**:

* An organization role is assigned on **People**. Team permissions in an organization role apply
  on every AI Team, including teams created later.
* An AI Team role is assigned per team, in the **AI Team access** grid on **People**.

To create one:

1. Open **People**, then the **Roles** tab, and select **New role**.
2. Start from a template (Billing manager, Auditor, Schedule operator, Contractor, Team lead or
   People admin), copy a system role, or start blank.
3. Name the role and choose the permissions it needs. Turning on a permission also turns on the
   permissions it depends on.
4. Select **Create role**.

Permissions marked **Sensitive** give access to billing, people, secret values or the audit log.
When you add one to a role that people already have, HQ asks you to confirm first. If your
organization requires two-factor authentication for admins, people with an organization role wider
than Member need it too.

## Preview a role [#preview-a-role]

To see HQ the way someone with a role sees it, open the role on the **Roles** tab of **People**,
and select **Preview**. HQ opens the dashboard as that role: pages, AI Teams and buttons appear the way
the role gets them. A banner at the top says which role you are previewing.

A preview is read-only. Nothing can be changed while it runs, even the things the role is allowed to
change; **What this role can change** in the banner lists those. The data you see is still yours,
and you only see AI Teams you can already see yourself. Select **Exit preview** to go back to the
role. A preview also ends when you switch organization, sign out or reload the page.

Every preview is recorded in the audit log as "Previewed a role".

## Check someone's access [#check-someones-access]

To find out whether a person can do something, open **People**, then the **Roles** tab, and select
**Open checker** under **Check someone's access**. Choose the person, the permission and, for a team
permission, the AI Team, then select **Check access**. HQ answers **Allowed** or **Not allowed** and
names the role or rule that decided it. You need permission to see roles and people to use it.

## New permissions [#new-permissions]

When HQ adds a permission, existing custom roles don't get it automatically. A role in the list shows
how many permissions are new since it was last edited. Open the role and select **Show new
permissions** to see only those, marked **New**, and turn on the ones the role should have.

## Rules no role can change [#rules-no-role-can-change]

Some things only one person can ever do, whatever their role:

* Only the owner of a session can type into it, change its permissions or share it, and only while
  they still have access to its AI team. An owner who can't see the team's sessions, through their
  role or because they were removed from the team, can't watch or type in their own sessions there.
* Personal secrets and variables belong to their owner.
* Only an owner can cancel the subscription, change the payment method or manage owners.
* You can only give permissions you have. A role you can't give is shown disabled with the reason.
* Only an owner can give role management (**Create and edit roles** and **Change roles**). Someone
  who manages roles through a custom role, like a People admin, sees both locked with "Only an owner
  can give role management".
* Nobody can change their own role.

These rules appear in the role editor as locked rows.

## Changing and archiving a role [#changing-and-archiving-a-role]

Editing a role changes it for everyone who has it. If two people edit the same role at once, the
second save is refused with "Someone else changed this role", and you can reload to see their
change.

To retire a role, select **Archive**. If people still have it, choose the role they move to.
An invitation into an archived role can no longer be accepted: the person invited is told the role
no longer exists and to ask for a new invitation.

When a change takes something away from people who have the role, it applies to their open sessions
too. Someone who can still watch a session but can no longer type sees "You can no longer type in
this session. You can still watch it." Someone who can no longer see the session sees that they
don't have access to it. If the role no longer lets them **Connect from a computer** on an AI Team,
any `hq attach` or VS Code terminal they have open on that team is closed. If they lose it on every
AI Team, their computer is also unlinked from the organization: when the role gives it back, they
link the computer again (sign in with `hq login` or the VS Code extension).

A permission that another one needs can't be turned off on its own. For example, **Read files
remotely** needs **Connect from a computer**: turn off both, or keep both.

Removing someone from an AI team, or leaving it yourself, ends their access to that team's sessions
at once, including the sessions they own there. Those sessions show that their owner left the team,
and nobody can type in them until a team owner or an organization owner or admin reassigns them.
Organization owners and admins reach every team, so removing their team access changes nothing.

## If your plan changes [#if-your-plan-changes]

If your organization moves to a plan without custom roles, existing custom roles keep working
exactly as they did for the people who have them. You can't create new ones, add permissions or
assign them, but you can remove permissions, move people to a system role and archive a role.
Moving back to Professional or Enterprise unlocks them again.
