Roles and permissions
A role is a named set of permissions. Everything a person can see and do in ITS comes from the roles on their account. What a role grants takes effect for everybody who holds it, immediately.
The Roles tab lists every role, shows what each one grants, lets the operator and the Secretariat change what a built-in role grants, and lets them build roles of their own when the built-in ones do not fit.
Who can open this screen
System admin, the operator who runs the deployment, and Secretariat admin.
| You are signed in as | What you see |
|---|---|
| The operator (System admin) | Users & roles has a Roles tab, with New role and every role for people. |
| The Secretariat admin | The same. |
| A State Party or REC administrator | No Roles tab. Typing its address shows You do not have access to this area and "Ask the Secretariat to check the role on your ITS account." |

To know what a role grants without this screen, read What each role can do.
Before you start
- You need System admin or Secretariat admin.
- Know which job you are describing. Most people need one of the built-in roles; a custom role is for a job none of them fits.
How to open it
- Select Users & roles in the header.
- Select the Roles tab.
The list shows the roles for people, including Localization admin, which lets a person correct ITS's translations in the localization service and grants nothing in ITS itself. Roles that belong to systems (partner systems, publishers, reconcilers, service accounts) are left out: nobody gives them to a person here. Use the role descriptions and What each role can do to confirm a role's purpose.
Under the table, "Member counts include only people in this organisation." The operator and the Secretariat admin both belong to the Secretariat, so Members counts the Secretariat's people only.
On the page
| On the page | What it is for |
|---|---|
| New role | Build a custom role. |
| Search roles… | Narrows the page of roles you are looking at by name or description. When the roles fill more than one page, a line under the table says how many on this page match and which page the search covers. |
| Status | Active only or Including inactive. |
| Clear filters | Shown while a search or Including inactive is in effect. It empties the search box and puts Status back to Active only. |
| Role | The name, a System or Custom badge, and the description. A padlock marks the one role nobody can change, System admin; every other role has a shield. |
| Permissions | How many permissions the role grants. |
| Members | How many people in this organisation hold it. |
| Status | Active or Inactive. |
| ⋮ (Role actions) | View, Duplicate, Edit and Deactivate (or Activate); Delete on a custom role only. System admin offers only View and Duplicate. |
Select a row, or View in its menu, to open the role's panel.

System roles and custom roles
| System roles | Custom roles | |
|---|---|---|
| Where they come from | Part of the deployment | Built on this screen |
| Badge | System | Custom |
| What you can do | View, Duplicate, Edit, Deactivate or Activate. Never Delete | View, Duplicate, Edit, Deactivate or Activate, Delete |
| Its machine name | Fixed | Fixed once the role is created |
System admin is the exception: it is the operator's recovery account, so no edit, deactivation or deletion reaches it. Its panel says "A system role ships with the deployment. It is read-only — the backend refuses every write against it."
The roles for people and the roles for systems are described in What each role can do. Only the roles for people appear on this screen and on Users.
Look inside a role
-
Select the role's row, or select View in its ⋮ menu. A panel opens on the right.

-
Read the panel:
Panel section What it shows Header The role's name, System or Custom, and Active or Inactive. Role Machine name (the role's fixed internal name, for example organisation-admin), Members in this organisation, Permissions (the count) and the description, with Edit and Duplicate.Permissions One line per area, with the actions granted on it: for example customs-officewithactivatecreatedeactivateexportimportreadupdate. No permissions. Anyone holding this role can sign in but do nothing. when it grants none.
The panel writes the areas with their internal names. The ones you will meet most, with the name the editor gives them:
| Area | In the editor | What it covers |
|---|---|---|
etd | Transit declarations | Declarations: read, and for systems issue (lodge), endorse (stamp), amend, attach, cancel, acknowledge. |
its-analytics, its-register, its-integration, its-workforce | Analytics reports, Register reports, Integration reports, Workforce reports | The Reports areas: Transit volumes and Time & delays; Register; Integration; Workforce. |
customs-office | Customs offices | The customs office register. |
governance | Governance datasets | Governance, and changing the rules and limits on Settings. |
intake-limit, transit-rule, operations-setting | Intake limits, Transit rules, Operations settings | Reading the three sections of Settings: Declarations, Transit rules and Operations. |
user, user-station | Users, Duty stations | Users (including reset-second-factor), and duty-station postings. |
authz-role | Roles | This screen. |
notification | Notifications | Notifications and the bell. |
onboarding, onboarding-self | Organisation onboarding, Self-service onboarding | The System integration area: every organisation's record, and an organisation's own. |
ledger | Ledger | The Consortium ledger. |
audit-trail | Audit trail | The Audit trail. |
The role editor
New role, Duplicate and Edit all open the same window.

| In the window | What it is for |
|---|---|
| Role name | The name people see, for example "Regional auditor". Required. |
| Description | Who the role is for (What this role is for…). |
| Permissions | "Click a permission to grant it — click again to remove. Click an area name to grant or remove all of it." |
| Search permissions… | Narrows the list to areas and actions whose name matches. |
| n of n granted | How many of all the permissions the role grants, with a bar. |
| Select shown | Grants every permission the search has left on screen: the whole list when nothing is typed. |
| Clear all | Removes every permission. |
The permissions are grouped by area: Transit, Onboarding, Reference data, Reports, Administration, Audit & ledger. Each area's band shows how many of its permissions are granted; select that count to grant or remove the whole area. Under it, each line is one part of ITS, such as Customs offices, with its actions as small tags, green when granted:
- Select a tag, such as Read, to grant or remove that one action.
- Select the line's icon or name to grant or remove all its actions.
The window keeps the save button greyed out until the role has a name and the whole list of permissions has loaded. If the list could not be read in full, the window says "The catalogue is larger than this screen loaded. Saving now would drop the permissions that were not read — reload before editing." Do what it says.
Closing the window with unsaved changes asks you first whether to discard them.
Change what a built-in role grants
A change to a built-in role, such as Customs officer, applies to every person who holds it as soon as you save. If only some people need different permissions, build a custom role instead.
- In the role's ⋮ menu, select Edit, or select Edit in its panel.
- The window Edit role says "Built-in roles keep their key; their permissions can be changed." Under Role name, "Referred to in the API as" names the role's machine name, "which cannot change".
- Change the name, the description or the permissions.
- Select Save changes, or Cancel.
Role updated confirms it. Editing a custom role works the same way; its window says "Update this role's details and permissions."
Deactivate, activate or delete a role
- Deactivate in the ⋮ menu marks a role Inactive. Role deactivated confirms it. To see inactive roles, set Status to Including inactive; Activate brings one back.
- Delete is offered on custom roles only. Delete this role? warns: "Name is removed for good — unlike a user, a role really is deleted. Anybody holding it loses what it granted. Deactivate it instead if you may want it back." Role deleted confirms it.
Build a custom role
The quickest way is to start from the closest existing role.
- In that role's ⋮ menu, select Duplicate. The Duplicate role window says it "Starts from what" that role grants: "Nothing is created until you name it and press Create — and the original is not touched." The name is left empty.
- Or select New role to start from nothing.
- Give the role a Role name people will recognise, and a Description saying who it is for.
- Choose the permissions in the role editor.
- Select Create copy (or Create role), or Cancel to keep nothing.
Role created confirms it, with the role's name. ITS makes the role's machine name from the name you typed; it cannot change afterwards. Open the role's panel to read it.
A role with no permissions can be created. Anyone holding it can sign in but do nothing.
Nobody can give a custom role to people on Users yet. The roles each kind of organisation may give are a fixed list set by the ITS team in ITS's configuration: for the Secretariat, Secretariat admin, Organisation admin, Customs officer, Departure authority and Partner; for a State Party, Customs officer and Departure authority; for a REC, Customs officer. A custom role is in none of them. To make one grantable, ask the ITS team to add it to the list for that kind of organisation. That is a configuration change, not a new release.