Roles & permissions
Permaura authorizes by capability, not by comparing role names. Every gated action names a capability, every route asks whether you hold it, and the role matrix is what maps roles to capabilities. That's why the answer to "can an admin do X?" is always lookup-able rather than a judgment call.
Owners see the live matrix for their organization at Settings → Roles & permissions.
The matrix
Four states per cell. Two of them you can change, two you can't.
| State | Meaning |
|---|---|
| Always | Granted, and not editable |
| Never | Withheld, and not editable |
| On | Granted by default; an owner can switch it off |
| Off | Withheld by default; an owner can switch it on |
Owner holds everything, always. There is no cell to edit and no override that removes anything from an owner. The table below is therefore admin and member only. Paying for the plan is not a capability, though: a change that raises what the payer is charged is the payer's alone, even for an owner, as the note under the Organization table sets out.
Organization
| Capability | Admin | Member |
|---|---|---|
| Rename organization | Always | Never |
| Delete organization | Never | Never |
| Manage billing & plan | Always | Never |
Deleting the organization is owner-only and unlockable. An admin can manage the plan but cannot remove the thing being billed.
Holding Manage billing & plan is not the same as paying. A change that raises what the payer is charged is only the payer's to make, the person whose card or account the plan bills, because it is charged to their saved payment method, and that holds for an owner too: adding seats or taking back a seat reduction, an upgrade on the same billing cadence, and switching a card subscription from monthly to annual. So is the billing portal. Any owner or admin can downgrade, remove seats or cancel. If the payer has left the organization, nobody can make those changes on that plan until an owner or admin takes over billing in their own name: by switching a monthly plan from a Merchant-of-Record checkout that still has a payer to annual billing, by canceling a card subscription or an annual plan and subscribing again, or, on a plan with no payer any more because the account that paid for it was deleted, by subscribing again from the billing page, canceling it first only if it is still renewing, as Managing your subscription describes.
Members
| Capability | Admin | Member |
|---|---|---|
| Invite members | Always | Never |
| Change roles / remove members | Always | Never |
| Edit role permissions | Never | Never |
Editing the matrix is owner-only and unlockable. An admin can hand out existing roles but cannot redefine what a role means, otherwise an admin could quietly grant themselves the rest.
Workspaces
| Capability | Admin | Member |
|---|---|---|
| Create workspaces | Always | Never |
| Rename / delete workspaces | Always | Never |
| Assign members to workspaces | Always | Never |
Gateways
| Capability | Admin | Member |
|---|---|---|
| Add the gateway | Always | Never |
| Remove the gateway | Always | Never |
| Enable / disable remote access | Always | Never |
| Install / remove connector definitions | Always | Never |
Giving a gateway a public URL changes the organization's exposure, so it sits with admins rather than with whoever happens to be operating that workspace today.
Operations: the tunable part
This is the day-to-day operator surface, and the only group with editable cells. Admins hold every row marked Always, hold Import a vault bundle by default, which an owner can switch off, and hold Export the vault and Remove any approval device alone only if an owner switches them on. Members hold every row marked On by default, and an owner can switch any of those off; the rows marked Off they hold only if an owner switches them on, and the row marked Never they cannot hold.
| Capability | Admin | Member |
|---|---|---|
| Add / configure connections | Always | On |
| Create / edit policies | Always | On |
| Create / edit grants | Always | On |
| Add / rotate sealed credentials | Always | On |
| Export the vault (all credentials) | Off | Off |
| Import a vault bundle | On | Off |
| Connect / approve / remove agents | Always | On |
| Open / revoke gateway sessions | Always | On |
| Approve or deny held requests | Always | On |
| Enroll / remove approval devices | Always | On |
Remove any approval device alone (device.remove.any) | Off | Never |
| Pause the broker / set approval gates | Always | On |
| Manage notification delivery | Always | Off |
Export the vault is the one capability that hands over credentials: an export writes every credential on the gateway into one bundle that opens with the exporter's passphrase. Give it to the people you would trust with every key, and see offboarding for what to rotate when one of them leaves.
Two limits sit outside the matrix, even with Enroll / remove approval devices on. On a hosted gateway with no trusted approval device, a member cannot pair the first one: that device confirms every later one, so it takes the gateway's owner or an owner or admin of the organization. Members pair theirs once a device is trusted. And a member can remove only an approval device they paired themselves on a hosted gateway; anyone else's takes an owner or admin, as does removing a device from the console or the app on a gateway you run yourself. From gateway 1.3.46 an owner's or admin's removal of someone else's device applies at once only for the gateway's owner or someone holding Remove any approval device alone; anyone else's waits for a device paired to someone else, or the gateway's owner, to confirm it, and lapses after 24 hours. Give that capability to an admin only if you would trust them to strip every other person's device: the devices left decide who can confirm a held change. See Enrolling an approval device.
A third limit holds even with Add / configure connections or Import a vault bundle. From gateway 1.3.47, a change that would send a stored credential somewhere new takes the gateway's owner or someone holding Export the vault, because the next call hands that credential to whatever host was chosen, as an export would. That covers an edit to an SSH connection's host, port, user, host-key fingerprint, host-key verification (--insecure) or password authentication; a new connection that would take over a credential already stored; and an import that would replace a connection or capability, or attach new ones to a credential already there. Anyone else is refused, and the refusal says who can make the change. On a hosted gateway this applies to every such change. On a gateway you run yourself it applies to one made from a web page, the console included, through permaura.com or from another machine, and not to the desktop app or the permaura command on the gateway's own machine.
Two patterns worth knowing
Making a read-only member
Switch every Operations capability off for the member role. They keep the console (dashboard, audit log, grants and policies as they stand) and can change nothing. Useful for an auditor, a stakeholder who wants visibility, or a new hire in their first week.
The narrower version is better if you only want one person read-only: leave the role matrix alone and scope them into a workspace as a viewer instead. See People & access.
Splitting "operates it" from "governs it"
A shape that works well in a team: members operate (they add connections, connect agents, resolve approvals) while grant.manage and policy.manage are switched off for them. Anyone can wire something up and run it; only admins can widen what it's allowed to do. It keeps the deny-by-default boundary in the hands of the people accountable for it, without making everyone wait on an admin for routine work.
Switching Approve or deny held requests off makes members unable to clear the queue. That's a real safety control, but if your admins aren't around often it turns every approval-gated action into a bottleneck. Decide which failure you'd rather have.
Overrides are per organization
A change to the matrix applies to that organization only. If you own two, they can differ, and the defaults above are what a fresh organization starts from. Switching a cell back to its default removes the override entirely rather than storing it, so "reset to default" and "never touched" end up in the same state.
When someone hits a wall
A capability check that fails produces one message: "You don't have permission to do this in this organization." It doesn't name the capability, deliberately: the error is user-facing and shouldn't teach an attacker the shape of your permission model.
To diagnose it, look up the action in the tables above, check the person's role at Settings → Members, and check whether an override has moved that cell. Almost every real case is one of three things: they're a member and the action is admin-only, an owner switched that Operations cell off, or they're scoped into the workspace as a viewer.