Roles and permissions
Give people exactly what their job needs — custom roles built from named permissions, assigned to members, mapped from your IdP, named on gates, and audited with what changed.
Every check in Minctrl asks one question: does this person's role hold a permission?
A permission is named (gate.approve, process.publish, member.invite); a role is a named
set of them; each member holds exactly one role.
The built-in roles
Every company has five roles that cannot be changed or deleted, and that hold exactly what they always did:
| role | what it is for |
|---|---|
| Owner | everything, including deleting the company and binding an irreversible action live. One per company; never removed, demoted or handed out. |
| Admin | the company's settings, members, roles, SSO, keys, audit export and governance. |
| Manager | signs gates (every tier) and runs the board. |
| Member | builds, starts and tests processes. |
| Viewer | reads runs and the audit chain, and starts runs. |
To change what a built-in role does, create a role based on it and give that to people.
Custom roles
Open Settings → Roles and choose New role. Name it ("Claims reviewer"), optionally
start from an existing role, and tick its permissions — grouped by area. Its key is made from
the name (claims_reviewer) and never changes, so a gate or an IdP mapping that names it
keeps working when you rename it.
curl -s -X POST "$API/roles" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Claims reviewer", "description": "Signs routine claims", "permissions": ["gate.approve"]}'Some permissions bring another with them, and the picker shows it checked:
| holding | also grants | because |
|---|---|---|
gate.approve | runs.read | you sign what you can read |
gate.approve.high_tier | gate.approve | |
process.publish | runs.read | |
connectors.bind_live | connectors.manage | |
audit.export | audit.read |
GET /roles/catalog lists every permission with its area, label and what it implies.
GET /roles/me tells a person what their role holds — the screens use it to say why a
button is disabled ("Needs the member.role.change permission — your role Claims reviewer does
not have it").
The permissions
| area | permission | lets a person |
|---|---|---|
| Gates | gate.approve | sign a parked gate (separation of duties still applies) |
gate.approve.high_tier | sign a gate that authorizes a live irreversible action — the ones the card asks you to confirm by typing the gate id. When Minctrl cannot tell (connectors not read, no pinned graph) it treats the gate as high tier. | |
delegation.manage | end another member's delegation | |
| Runs | runs.start, runs.read | start runs; list and open runs |
| Processes | process.edit | save, import and delete drafts; submit your own version |
process.publish | publish, roll back, return someone else's version | |
process.test | write and run test suites | |
| Members | member.invite, member.remove, member.role.change | invite and approve join requests; remove; change roles |
roles.manage | create, change and delete custom roles | |
| Connectors | connectors.manage, connectors.bind_live | change connectors and connections; let an irreversible action run live |
| Identity | sso.manage, sso.domain.attest | the SSO connection, domains, group mapping and SCIM token; confirm a domain without DNS |
api_keys.manage, triggers.manage | API keys; webhook and schedule triggers | |
| Audit | audit.read, audit.export | read and verify the chain; export it, evidence packs, SIEM sinks, timestamping |
access_review.confirm | open and confirm the quarterly access review (owner by default) | |
| Settings | settings.governance, notifications.manage, company.update, company.delete, llm_keys.set | governance policy; notification channels; the company profile; deleting the company; model keys |
| Board | project.*, ticket.create, ticket.assign | projects; columns and tickets |
API keys are not roles: a key acts only by its scopes and never signs a gate.
Guardrails
- Only
roles.managechanges roles (owners and admins by default). - Nobody grants a permission they do not hold. Creating or editing a role, assigning it to
a member, inviting someone with it, mapping an IdP group or the SSO default to it — each is
refused (
403) when the role holds a permission you do not. You also cannot change or delete a role, or change the role of a member, holding a permission you lack. An admin cannot make anyone an owner, and cannot hand outcompany.deleteorconnectors.bind_live. - There is always exactly one owner. The owner role is never edited, deleted, assigned, demoted or removed.
- A role in use is not deleted. While a member (active, invited, awaiting approval or
suspended), an IdP group, or the SSO default role holds it,
DELETE /roles/{key}answers409and names them. Give them another role first.
Assigning roles
On Settings → Team, the role picker lists the built-in roles and the company's custom roles. A member holds one role at a time; a change takes effect on their next request.
From your IdP
The group → role mapping may name any role, built-in or custom, and so may the role for a new member. With several mapped groups, the role holding the most permissions wins (for the built-in roles that is their usual order, owner first). SCIM group changes use the same mapping.
Gates that name a role
A gate's approvals.roles may name a custom role's key next to owner, admin and manager:
{"approvals": {"required": 2, "order": "sequential", "roles": ["claims_reviewer", "manager"]}}The signer must still hold gate.approve (and gate.approve.high_tier for a live
irreversible action), and separation of duties is unchanged. A gate that names a role nobody
holds cannot be signed until someone is given it — delete roles with care.
Audit
| entry | records |
|---|---|
role_created | the role, its name, what it was based on, permissions_after |
role_changed | what changed, added, removed, permissions_before, permissions_after, how many hold it |
role_deleted | the role and permissions_before |
member_role_changed, member_invited, member_joined | the role from/to plus permissions_before / permissions_after |
Every entry names who made the change and their role, and lands in the hash-linked chain in the same transaction as the change.
Upgrading
The migration infra/migrate_custom_roles.sql seeds the five built-in roles for every
existing company (and, by a trigger, for every new one), and makes memberships.role, the
group mappings and the SSO default role refer to a company's roles. It changes nobody's role
and nobody's permissions; it can be re-run.
Set up your team
Register (open), get your auto-created company, then invite members and assign roles — all company-scoped, so a teammate only ever sees your company's data.
API keys and service accounts
Give a script or an integration its own company credential — scoped to what it needs, shown once, revocable at once, and never able to sign a gate.