Roles & permissions

Who can do what in an organization: its owner, Everyone, and the roles you make.

What somebody may do in an organization comes from its roles. A role is a named set of the organization's members — Release managers, Design, Support — with a colour and a list of permissions. A person can hold several roles, and may do everything any of them allows.

A role with no permissions is still useful: it is a team you can name. Gate approver rules, comment mentions, dashboards, monitor alerts, apps and buttons can all name a role, and each means whoever holds it at the time.

Where roles are kept

Roles sits beside Members: the Roles tab of the Members page on the web and the desktop app, and the row after Members in the organization's settings on the Mac, iPhone, iPad and Android. Every member sees the roles and who holds each; only people with Manage roles see what each role may do.

Open a role to change its name, its colour, whether Anyone can @mention this role, its permissions and its members. New role adds one at the bottom of the list, just above Everyone. Members shows the same roles from the other side: each person with theirs.

See as…, for people with Manage roles, shows what Everyone, a role or a person gets at the organization — or an API key, for people who also hold Manage API keys — and Why? beside each permission names the roles that give it, or the key's own list. A project's Access page asks the same in the project, or at a folder or file, where it can also see as one of the project's triggers (Private projects & access).

The owner

Every organization has exactly one owner: whoever created it, until they hand it over. The owner stands outside the roles, may do everything, and can't be locked out. Two things are the owner's alone — deleting the organization, and handing it over.

To hand it over, the owner chooses Make owner… on a member in Members. That member is told in their Inbox — "Alice offered you Acme" — and becomes the owner when they accept it in Members. Until then the owner can withdraw the offer, and the member can decline it. The old owner stays a member, with the roles they had.

The owner can't leave without handing the organization over first. Deleting your account is refused while you own an organization other people are in; one you are alone in is deleted with the account.

Everyone

Everyone is the role every member holds, from the moment they join. It can't be deleted, renamed, recoloured or taken from anybody: only its permissions and its mention switch change. In a new organization it holds View project, Start runs, Create tasks, Manage planning, View files, Edit files and Create branches.

So a new member can start and follow runs, work the board, plan milestones and cycles, and read and commit code, wiki pages and assets — but can't act on other people's runs, delete or merge tasks, moderate other people's comments, or make public links. Change what Everyone holds to change what every member may do. A project can change it for itself, and a private one keeps Everyone out.

A new organization has its owner and Everyone, and no other role.

Order

Roles are ranked, highest first, and people with Manage roles drag them up or down the list to reorder them. You can only change, move, give or take away the roles below your own highest role, and only remove members whose roles all sit below it. The owner is above every role.

Holding Manage roles isn't enough to hand everything out. Giving somebody a role, or taking it away, also takes every permission the role grants; ticking a permission on a role takes holding it yourself. A permission you don't hold can't be ticked, though it can be unticked. The same goes for what you give an API key or a trigger (below).

Administrator

Administrator is a permission, not a role. It grants every other permission, in every project whatever that project's access says, and passes the ranking: whoever holds it can change, give and take every role. It never reaches what is personal to somebody else — their own dashboards, assistant conversations, notifications and connected apps.

An "Admins" role

Peractor makes no roles for you beyond Everyone. For admins, make a role called Admins, tick Administrator, and add the people. Ticking every other permission instead gives the same powers inside the ranking: its holders can only change, give and take the roles below it, and can't give Administrator.

The permissions

The role editor lists them on six shelves, with Administrator above them all. ✓ marks what Everyone holds in a new organization. What a role holds, it holds in every project, unless the project, or a folder or file in it, sets its own answer: Private projects & access says which permissions each can set.

Some things need no permission: your own account, sessions and devices; your notifications; your assistant conversations; your personal and listed dashboards; your connected apps; your own saved views; and leaving. Approving a gate is decided by the phase's approver rules; the only permission it takes is View project, in the run's project — and, for a run that worked with restricted folders or files, being able to open them.

API keys and triggers

An API key and a trigger hold no roles. Each can have a permission list of its own instead, ticked on the same shelves as a role's:

• An API key starts with nothing and holds only what it is given, in Settings → API keys, by people with Manage API keys.
• A trigger is given one on its page in the Triggers library, by people with Manage roles. Without one it acts with no identity: it sees only what Everyone can.

Either way you can give only permissions you hold yourself. A key, or a trigger with a list, gets nothing that Everyone or a role is given, and what a project closes to Everyone stays closed to it until the project's Access page names it — see Private projects & access.

Naming a role elsewhere

• Gate approvers — { role: [release-managers] } in a phase's approvers:, or a role picked in the workflow editor's Reviewers section. Whoever holds it when the gate is decided may approve. See Gates & reviews.
• Mentions — @Release managers in a task comment tells everyone holding the role, when its Anyone can @mention this role switch is on — as it is for a new role, and isn't for Everyone. People with Manage roles can mention any role.
• Dashboards — share a dashboard with people and roles, and everyone holding one of them reads it.
• Monitor alerts — a monitor tells the people and the roles it names when it goes down or comes back.
• Apps — a listed app opens for the people and roles it names. See Apps you build.
• Buttons — a button can be pressed only by the roles and people it names, who also need Start runs. One that names nobody is left to Administrator holders and the owner.

Naming Everyone means every member.

Deleting a role

Everyone can't be deleted. Deleting any other role first lists where it is named — the gates of each workflow, dashboards, apps, buttons and monitors, and how many projects' access settings — and confirming takes it out of all of them. A gate whose only approver rule named the role then admits nobody until somebody edits it; it never falls back to letting every member approve. A dashboard shared only with the role goes back to its owner alone.

Next: Private projects & access · Accounts, organizations & members · Gates & reviews