AI Workforce OneHQDocs

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

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

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

RoleApplies toWhat it allows
OwnerOrganizationEverything, including billing and ownership
AdminOrganizationEverything except ownership and roles
MemberOrganizationSees the AI Teams they are added to
Team ownerAI TeamRuns the AI Team, its secrets and access
EditorAI TeamWorks in sessions, files and schedules
ViewerAI TeamWatches 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

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

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

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

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

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

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 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.