Roles

A role is a named bundle of permission strings. A role assignment attaches a role to a principal inside a project. Principals can be humans, machine identities, or agents.

That is the project access-control surface: assignments decide what humans can do in the app, what API keys can do through their API client principal, and what agents can do through their own agent principal.

Org roles and project roles

Mobius has two related layers:

Owner and Admin are both useful, but they are intentionally distinct. Owner is the governance role: owners can delete the organization and manage owner access. Admin is the day-to-day operator role: admins can manage members, settings, projects, and integrations, but cannot delete the organization or promote, demote, or remove owners.

Invitations can assign Member or Admin. To add another owner, invite them as Admin, then promote them after they accept so ownership is attached to a real Mobius principal.

Start with system roles

Most teams should start with the system roles:

System roles are assignable but immutable. If a workload needs less than a system role, create a custom project role.

When to write a custom role

Custom roles fill the gaps when no system role matches. Three patterns come up:

• Single-action runner. A CI API client that can start runs and invoke one specific action, such as actions.execute.deploy.prod.
• Read-only audit. A compliance integration that reads audit logs but should never see secrets or mutate resources.
• Owned-resource operator. An agent or API client that should manage only resources it owns, using owned permission variants where the catalog exposes them.

If you find yourself wanting a role that "almost matches" a system role, create a custom role from the current permission catalog and trim it deliberately.

Permission catalog

Permission strings are validated by the backend. Do not copy a static list from an old doc; inspect the live catalog for the project:

mobius permissions list

The same data is available at:

GET /v1/projects/{project}/permissions

Common project permissions include:

mobius.project.view
mobius.project.manage
mobius.access.manage
mobius.automations.manage
mobius.automations.manage_owned
mobius.runs.operate
mobius.runs.operate_owned
mobius.work.execute
mobius.integrations.read
mobius.integrations.manage
mobius.audit.view
 
actions.execute.{action_name}
actions.execute.*

The catalog response also includes assignability, risk, category, and which principal kinds the permission can apply to.

Working with roles from the CLI

# Inspect
mobius roles list
mobius roles list-assignments
mobius permissions list
 
# Create a custom role
mobius roles create \
  --name deploy-runner \
  --permissions mobius.project.view \
  --permissions mobius.runs.operate \
  --permissions actions.execute.deploy.prod
 
# Assign it to a principal
mobius roles create-assignment \
  --principal-id prin_01... \
  --role-id rol_01...
 
# Tear down
mobius roles delete-assignment ra_01...
mobius roles delete rol_01...

Use mobius roles list -o json when you need a role ID for another command:

WORKER_ROLE_ID="$(mobius roles list -o json \
  | jq -r '.items[] | select(.name=="Worker") | .id')"

A tip from production

Do not assign broad admin roles as the day-to-day role for an API client. Workers should usually be Worker, dashboards should be Viewer, and deploy bots should get the narrow custom permissions they actually need. Reserve Owner and Admin for humans so the audit log attributes the action to the person making the change.

Related

• Machine identities explains the principals roles attach to.
• API keys authenticate as API client principals; roles decide what those clients can do.
• Agents act through agent principals and pick up whatever roles those principals hold.
• Audit logs record the principal and credential for every mutation.