Minctrl Docs
Guides

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:

rolewhat it is for
Ownereverything, including deleting the company and binding an irreversible action live. One per company; never removed, demoted or handed out.
Adminthe company's settings, members, roles, SSO, keys, audit export and governance.
Managersigns gates (every tier) and runs the board.
Memberbuilds, starts and tests processes.
Viewerreads 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:

holdingalso grantsbecause
gate.approveruns.readyou sign what you can read
gate.approve.high_tiergate.approve
process.publishruns.read
connectors.bind_liveconnectors.manage
audit.exportaudit.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

areapermissionlets a person
Gatesgate.approvesign a parked gate (separation of duties still applies)
gate.approve.high_tiersign 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.manageend another member's delegation
Runsruns.start, runs.readstart runs; list and open runs
Processesprocess.editsave, import and delete drafts; submit your own version
process.publishpublish, roll back, return someone else's version
process.testwrite and run test suites
Membersmember.invite, member.remove, member.role.changeinvite and approve join requests; remove; change roles
roles.managecreate, change and delete custom roles
Connectorsconnectors.manage, connectors.bind_livechange connectors and connections; let an irreversible action run live
Identitysso.manage, sso.domain.attestthe SSO connection, domains, group mapping and SCIM token; confirm a domain without DNS
api_keys.manage, triggers.manageAPI keys; webhook and schedule triggers
Auditaudit.read, audit.exportread and verify the chain; export it, evidence packs, SIEM sinks, timestamping
access_review.confirmopen and confirm the quarterly access review (owner by default)
Settingssettings.governance, notifications.manage, company.update, company.delete, llm_keys.setgovernance policy; notification channels; the company profile; deleting the company; model keys
Boardproject.*, ticket.create, ticket.assignprojects; columns and tickets

API keys are not roles: a key acts only by its scopes and never signs a gate.

Guardrails

  • Only roles.manage changes 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 out company.delete or connectors.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} answers 409 and 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

entryrecords
role_createdthe role, its name, what it was based on, permissions_after
role_changedwhat changed, added, removed, permissions_before, permissions_after, how many hold it
role_deletedthe role and permissions_before
member_role_changed, member_invited, member_joinedthe 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.

On this page