Roles and permissions

Everything anyone can do in UnitX is gated by a permission, such as project.view or finance.approve. A role is a named set of permissions, and every member holds exactly one role in each organization. Roles let you give people the access their job needs — no more, no less.

Key concepts#

Permission

One capability, named area.action — for example invitation.create or integration.approve. Reading and changing are always separate permissions.

Role

A named set of permissions. What a role can do is exactly the permissions ticked in it, nothing implied.

System role

One of the five roles every organization starts with. They cannot be edited or deleted.

Custom role

A role your organization creates, with the permissions you choose.

Scope

An optional condition on one permission inside a role, narrowing it to the person’s own records, their direct reports or their department.

Who can manage roles#

The five system roles#

Create a custom role#

1. Open the Roles tab

   Go to SettingsRoles and choose New role.

2. Name and describe it

   In Create a custom role, enter a Name (required) and a Description. The description is shown in the role list, so use it to say who the role is for.

3. Tick the permissions

   Permissions are grouped by area. Tick each one the role should include.

4. Optionally narrow a permission

   When you tick a permission a scope selector appears beside it. Leave it on Any record, or choose a narrower scope (see below).

5. Choose Create role

   The role appears in the list. Assign it to people from the Members tab.

Edit or delete a custom role#

Choose Edit next to a custom role. In Edit role you can rename it, tick or untick permissions and change scopes, then choose Save changes. The change applies to everyone holding the role on their very next request.

To delete the role, choose Delete role in the same dialog. A role that is still assigned to anyone cannot be deleted — you will see This role is assigned to at least one member and cannot be deleted — reassign those members first.

Narrowing a permission with a scope#

A scope keeps a permission but limits which records it reaches. The person still needs the permission itself; the scope decides how far it goes. The role list shows how many permissions in a role are scoped, for example “· 2 scoped”.

Any record

No scope. The permission reaches every record.

Their own records

Only records the person owns — for example teams they created or manage.

Their direct reports

Only records about people who report to them, taken from the manager set on employee records.

Their own department

Only records in the same department as the person.

Custom (set elsewhere)

Shown when a permission carries a condition that was set through the API and cannot be described by the choices above. Pick one of the other options to replace it.

Examples#

• Team lead: team.view and team.manage scoped to Their own records, so a lead runs their own teams and sees no others.
• Line manager: member.view scoped to Their direct reports, so the member list shows only their own people.

Limits of scopes#

• Some pages act on many records at once, or on none, so there is nothing to measure a scope against. Those requests are refused rather than treated as unrestricted. If a scoped permission blocks a page people need, grant that permission without a scope.
• Direct reports and departments come from your people records. An organization that keeps no employee records has no reporting lines, so those scopes match nothing.
• API keys and service accounts cannot use a scoped permission — a scope describes a person, and an integration has no records of its own or reports.

Assigning roles#

• People: choose a role when you invite them, or change it later in the Role column on SettingsMembers.
• Service accounts: choose a role when you create one, or change it on SettingsService accounts.
• External collaborators start as Guest. Whatever role they are given later, they can never manage members, roles, invitations, billing or organization settings.

Reading the permission list#

The permission picker lists every permission UnitX has, grouped by area, with a plain-language name. Each page of these docs lists the keys its feature needs. The keys that matter most for administration are:

member.view

View organization members (and open Settings).

member.invite

Invite organization members.

invitation.create

Create invitations.

invitation.revoke

Revoke invitations.

member.manage_roles

Change members’ roles.

member.remove

Remove, suspend and sign out members.

organization.manage

Manage organization settings.

organization.delete

Delete the organization (Owner only).

sso.manage

Configure domains and single sign-on.

scim.manage

Manage SCIM provisioning credentials.

service.manage

Create and manage service accounts.

audit.view

View the organization’s audit log.

data_governance.manage

Set retention, legal holds and classifications.

Related pages#

• Members and invitations
• External collaborators
• Data classification
• Key concepts