Roles

A role is a set of permissions. Under Settings → Roles you see what each role allows and who holds it, and make roles of your own. You give roles on a person's page under Users.

Units and roles work together. A person sees the cases of the units they work in (and every unit below); their roles say what they may do there.

A role is held everywhere, or in a unit and everything below it: someone can be an Agent in Billing only, or an Analyst everywhere.

References

Every role and permission has a technical reference next to its friendly name, for troubleshooting, the audit log and the API:

Reference	Format	Examples
Permission keys	<area>.<what>	case.read, case.write, incident.send_update
Role keys	The desk's roles by name; <area>.<role> for a plugin's; custom.<name> for your own	admin, agent, viewer; incident.manager; custom.second-line
Role ids	The database ids the API uses	/api/v1/roles/{id}

Most areas have read (see it), write (change it), delete and settings (configure the area); a few steps have a named permission of their own, like case.merge or incident.change_priority. Areas are singular, and a plugin that extends another sits under its area: Major Incident Management's incident.major.declare, the Status Page's incident.status.publish.

A role's page shows its key and id, each with a copy button, and every permission with its key.

What read permissions do

Read permissions decide what someone sees, inside the units they work in. Without case.read someone sees no cases, wherever they work; with it only in Billing, they see Billing's cases only. The same goes for incident.read, account.read, contact.read, user.read, team.read and role.read.

[!NOTE] Seeing is not working: someone who holds case.read but not case.write in a unit reads its cases, can't change them, and isn't offered as an assignee.

Built-in roles

Built-in roles come with the desk and its plugins. Each holds a whole area, so the role is easy to reason about. Nobody can change or delete them, Administrators included, and no role of your own can take their names.

Role	Key	Allows
Administrator	admin	Every permission, everywhere, including those of plugins added later. Administrators see every unit. At least one person always has the role.
Agent	agent	Everyday case work: case.read, case.write, case.create, case.merge; account.read, contact.read, contact.write; with Incident Management, incident.read and incident.write; with Service Configuration, service.read. New people get it.
Viewer	viewer	Reads and changes nothing: case.read, account.read, contact.read, report.read, incident.read and service.read. For stakeholders and auditors.
Analyst	analyst	report.read, and case.read for the cases behind them.
Account Manager	account_manager	Everything about accounts and contacts: account.read, account.write, account.delete, contact.read, contact.write, privacy.export, privacy.erase; and agreement.read and agreement.write: agreements from templates.
Service Delivery Manager	service_delivery_manager	Agreements with accounts: agreement.read, agreement.write and agreement.manage (agreements without a template, deleting them, and the templates under Settings → Agreements); with account.read and contact.read.
Service Level Manager	sla_manager	sla.settings: service levels and business hours.
Auditor	auditor	Reads everything an audit needs and changes nothing: case.read, account.read, contact.read, agreement.read, report.read, audit.read (the audit log and the export log), user.read, team.read, role.read, and audit.evidence, audit.config and audit.logged; with their plugins, incident.read, problem.read, change.read, service.read and access.read. Everything they open or export is logged. Give it for the engagement's period (roles for a period), in the units in the audit's scope. See compliance and audit.
Access Manager	access_manager	user.read, user.write, team.read, team.write, role.read, role.write, everywhere: every role except Administrator. With Access Management, access.read, access.write and access.settings.

Plugins add built-in roles of their own:

Role	Key	Allows
Problem Manager (Problem Management)	problem.manager	Problems: problem.read, problem.create, problem.edit, problem.manage (owner, close, merge, risk acceptance, sign-off) and problem.settings.
Change Manager (Change Management)	change.manager	Changes: change.read, change.write, change.approve, change.manage (override the risk, reschedule and cancel others' changes, proceed without a customer's answer), change.template and change.settings.
Change Approver (Change Management)	change.approver	change.read and change.approve: approves the changes a policy asks them to (a CAB member).
Service Manager (Service Configuration)	service.manager	The service catalogue: service.read, service.write (records and the accounts using them), service.approvers (accounts' change approvers and notice contacts) and service.settings (add services and offerings, change their status, delete unused ones).
Incident Manager (Incident Management)	incident.manager	Every incident permission, and those of Major Incident Management and the Status Page when they are on: work on incidents, send updates, change priority, delete, declare and run major incidents, publish on the status page, and all their settings.
Incident Responder (Incident Management)	incident.responder	incident.read, incident.write, incident.send_update, and incident.major.write to work on major incidents.

People who were agents before roles existed are Agents and Analysts, so they kept their reports. Admins became Administrators (and Agents).

Permissions

The desk's permissions, by area. Settings → Roles lists them with their hints, and plugins' under their own area.

Area	Key	Lets them
Cases	case.read	See the cases of the units they work in, with their conversations
	case.write	Reply, add notes, change status, priority, assignee, team, labels and unit; accept or reject held requests
	case.create	New case: phone calls, walk-ins and everything else
	case.merge	Merge a case into another from the same requester
	case.legal_hold	Set and lift a legal hold on a case, problem or change
	case.approve	Give the approval a process control asks for on a case they don't handle themselves
	view.share	Views everyone sees in their sidebar (sharing with people, teams and units needs nothing)
Customers	account.read	See accounts
	account.write	Create and edit accounts, and move contacts between accounts
	account.delete	Delete an account (its contacts and cases stay)
	contact.read	See contacts
	contact.write	Create contacts and edit their details
	privacy.export	Export everything about a contact (an access request)
	privacy.erase	Erase a contact and everything about them (an erasure request)
Insight	report.read	Reports, counting the cases they can read
	audit.read	Settings → Audit log, and the export log (Settings → Exports)
	audit.evidence	Audit evidence: the controls and their results, the exceptions, populations, samples and evidence packs
	audit.config	Read the configuration: Settings → Configuration, and conflicts of duties
	audit.logged	Reading is logged: every record and list they open goes in the audit log, their exports in the export log (for auditors)
	control.settings	Process controls: define, change and switch them off, and explain exceptions
Service	sla.settings	Service levels and business hours
	rule.settings	Settings → Automations
	survey.settings	Satisfaction surveys, and which units send them
Channels	form.settings	Forms, their security and IP allowlists
	portal.settings	Portals, their pages and domains
	brand.settings	Brands: names, logos, colours, senders and signatures
	email.settings	Inbound email settings and the review of refused emails
People and organization	unit.settings	Organizations and units
	user.read, user.write	See users; invite, edit and disable them
	team.read, team.write	See teams; create, change and delete them, their members and units
	role.read, role.write	See roles and who holds them; your own roles, and giving and taking away roles
Installation	token.settings	See and revoke anyone's API tokens and AI assistant connections
	webhook.settings	Webhooks and their deliveries
	housekeeping.settings	What is deleted when
	property.settings	Data properties: add, change and archive them
	installation.settings	Installation settings, languages and plugins

Plugin permissions:

Plugin	Key	Lets them
Incident Management	incident.read	See the incidents that affect the units they work in
	incident.write	Declare incidents, change status, commander, category and units, add notes, link cases, write the review
	incident.send_update	Send updates to the requesters of the linked cases
	incident.change_priority	Change priority, impact and urgency after declaring
	incident.delete	Delete an incident for good
	incident.settings	Settings → Incident Management
Major Incident Management	incident.major.write	Work on major incidents: roles, steps, stakeholder updates, child incidents
	incident.major.declare	Declare and stand down major incidents
	incident.major.settings	Settings → Major Incident Management
Status Page	incident.status.publish	Put an incident on the status page and send updates there
	incident.status.settings	Settings → Status Page
Access Management	access.read	Access history
	access.write	Run access reviews
	access.settings	Access Management's settings

A permission counts when it is held everywhere or in one of the units the case or incident belongs to.

[!NOTE] A plugin's permissions and built-in roles show only while the plugin is on. Turned off, they leave this page and people's pages, but stay on the roles and people that have them: saving a role keeps them, and they count again when the plugin is turned on again.

Roles for a period

When you give a role on a person's or a team's page, Until (optional) sets the last day it counts: for an auditor's engagement, a temporary stand-in or a project. The role is shown with “until” and the date.

• It stops counting at the end of that day, and the hourly job removes it. Access Management's history records it as revoked, like a role taken away by hand.
• Giving the same role again changes the date (or, with no date, removes the end).
• Role holders under Settings → Configuration lists every role with its end.
• Over the API: endsAt on POST /api/v1/role-assignments (the audit API).

Your own roles

New role, or Duplicate on any role but Administrator, opens the role:

Field	What it is
Name	Unique, and not a built-in role's.
Key	Made from the name (custom.second-line) until you change it: custom. and lower-case words joined by dashes. It can't be changed after the role is made, so scripts and notes that use it keep working.
Description	Optional.
The permissions	By area. Pick a whole area with its checkbox, or exactly the permissions a job needs; Find a permission searches names and keys.

Edit and the delete button are on your own roles only.

[!WARNING] Deleting a role takes it from everyone who held it.

Who may give which role

Administrator is given only by an Administrator, and only everywhere. The other roles:

Who	May give
Someone who manages roles everywhere (Access Manager)	Any other role, everywhere or in any unit, and makes roles of their own.
Someone who manages roles only in a unit	Roles there and below, and only roles whose permissions they hold there themselves.

[!IMPORTANT] Nobody but an Administrator gives a role to themselves.

Every role given or taken away is in the audit log, and in Access Management's history when that plugin is on.

When a plugin's role has your role's name

The built-in roles of every plugin in your installation are known even while the plugin is off, so their names are already taken. A plugin added to the installation later could bring a role with the name of one of yours. Then Settings → Roles says so, and an Administrator chooses Use the built-in role: your role becomes the built-in role, and everyone who held it keeps it, with the built-in role's permissions instead of yours.