Roles
The eight seeded roles, how they stack, and how to author a role of your own
Overview
A role is a named bundle of grants. You assign a role to a person, or to a group, and they get its grants.
MagOneAI ships eight seeded roles that reproduce the access model that existed before, exactly. You can also author your own roles.
The seeded roles
| Role | Scope | Reach |
|---|---|---|
| Default | Everyone | The floor every person holds with no assignment at all |
| Project Viewer | Project | Read the projects they belong to, including their own runs and files |
| Project Operator | Project | Run use cases, and read their own runs |
| Project Builder | Project | Author and publish use cases, agents and knowledge bases |
| Project Admin | Project | Administer the project, including its members |
| Organization Admin | Organization | Administer the organization, its projects and its members |
| Organization Owner | Organization | Everything an Org Admin can do, plus the highest-trust organization actions |
| Platform Superadmin | Platform | Everything, everywhere. The break-glass role. |
The project roles stack
The five project-level roles are cumulative. Each contains everything in the one before it.
Default ⊂ Project Viewer ⊂ Project Operator ⊂ Project Builder ⊂ Project AdminSo a Project Builder can do everything an Operator can, and an Operator everything a Viewer can. You never need to assign two of these to the same person for the same project.
The two organization roles stack the same way: Organization Owner contains Organization Admin.
The Default role is undeletable. It is the access floor, so there is always something for a person with no other assignment to hold. You can edit what it contains, but be careful: emptying it affects every person in the organization at once.
Why the seeded roles use wildcards
A seeded role's grants are wildcards, meaning "on the projects you can already reach". That is what makes them reusable across every project without listing them.
It is also why they are not a way to give someone access to a new project. For that you need an explicitly targeted grant. See wildcard and explicit targets.
How a person gets a role
Four sources combine, and all four are real at the same time.
Everyone holds it. Nothing assigns it; it is the floor.
Joining an organization or a project writes a role assignment at that moment. This happens on every membership path, not only the obvious one, because a path that wrote no role would leave the person holding nothing and falling through to the loud fail-open.
An org admin assigns a role from the Access screen, optionally scoped to one target.
The group's role applies to every member. See Groups.
Authoring your own role
Create a custom role when the seeded ladder does not describe the shape you need. Two common cases:
- A population that needs one specific action and nothing else, for example running a single published use case
- A population that needs most of a tier but must be denied one thing
Create the role
In the Admin Portal, open Access Control, select the organization, and use the Roles tab. Give the role a name that says who it is for, not what it contains, because what it contains will change.
Add permissions
Each permission is an action plus the level it attaches to, and optionally a specific target.
Only actions you hold can be added. See You cannot grant what you do not hold.
Decide wildcard or explicit target
Leave the target empty for a wildcard, which narrows what the holder may do where they already are. Name a target to establish access to that one object.
For "run this one use case", you want an explicit target.
Add denies where you need them
A deny beats every allow. Use it to carve an exception out of a wide grant rather than building a narrower role from scratch.
The grant ceiling does not apply to denies, so you can deny an action you do not hold yourself.
Assign it
Assign the role to a group if more than one person needs it, and directly to a person only for a genuine one-off. See Groups.
Saving a role's permissions replaces the whole set. It is not a merge. Read the existing rows before you save, or you will drop scoped and deny permissions that someone else added.
Reading what a role actually grants
Two places answer this, and they answer different questions.
| Surface | Answers |
|---|---|
| Roles page in the Admin Portal | What does each seeded role contain? A read-only matrix. |
| Effective permissions tab on the Access Control page | What does this person actually hold, from all four sources combined? |
Always check effective permissions before concluding that a role is wrong. A person's access is the union of four sources minus every deny, so a role rarely tells the whole story on its own.
Good practice
The seeded ladder covers reading, running, building and administering. Most requests are one of those four, and a seeded role needs no maintenance.
"Finance reviewers" survives a permission change. "Can run and view" does not.
A role on a group is one change when the population changes. A role on twelve people is twelve.
One wide role plus a deny is easier to audit than two similar roles that drift apart.
It is the floor for everyone in the organization. Widening it widens everyone; emptying it has removed access for a whole organization before.
Troubleshooting
Cause: The role's grants are wildcards, which narrow what someone may do where they already are. They do not establish access to a new project.
Fix: Either add the person to the project, or add an explicitly targeted grant naming that project.
Cause: The grant ceiling. You do not hold the action you are trying to add.
Fix: Ask someone who holds it, or have a platform superadmin make the change.
Cause: Saving replaces the whole permission set rather than merging.
Fix: Re-add them. To avoid a repeat, make role edits from the current state of the role rather than from a remembered one.
Causes to check: a group they belong to carries another role, they hold a direct assignment as well, or a per-person override was added.
Fix: Read Effective permissions for that person, which shows all sources at once.
Cause: This is working as designed. Holding no role is a seeding gap and fails open with a loud log entry. Holding a role that grants nothing is a policy outcome and denies.
Fix: If the person should hold a role, find out why no role was written. A membership path that does not seed a role is a defect worth reporting.