A role is a named collection of permissions assigned to actors — users or service accounts — via role assignments. Roles control what each actor can do within an org or within a specific project. Mobius provides system-defined roles that cannot be modified or deleted; you also create custom roles scoped to your org or to individual projects.

The model

Each role has:

• A scope — system-defined roles have no org_id or project_id and apply platform-wide; org-wide custom roles carry an org_id but no project_id; project-scoped custom roles carry both.
• A permissions list — strings such as "mobius.workflow.create" or "mobius.job.claim" that enumerate what the role grants.
• A system_defined flag — true for built-in platform roles that cannot be modified or deleted.

A role assignment binds an actor (a user or service_account) to a role. Assignments are optionally project-scoped: omit project_id for an org-wide grant, or supply it to restrict the grant to one project. Every assignment records the creating actor in granted_by_actor_type and granted_by_actor_id for audit. Deleting a role hard-deletes it together with all its assignments.

Creating and assigning a project-scoped role

# 1. Create a custom role scoped to project proj_abc
curl -X POST "$MOBIUS_API_BASE_URL/roles" \
  -H "Authorization: Bearer $MOBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workflow-runner",
    "description": "Can create workflows within the project.",
    "project_id": "proj_abc",
    "permissions": ["mobius.workflow.create"]
  }'
 
# 2. Assign the role to a service account within the same project
curl -X POST "$MOBIUS_API_BASE_URL/role-assignments" \
  -H "Authorization: Bearer $MOBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_type": "service_account",
    "actor_id": "sa_xyz",
    "role_name": "workflow-runner",
    "project_id": "proj_abc"
  }'

Mobius creates the workflow-runner role within proj_abc, then binds service account sa_xyz to it for that same project. The service account gains mobius.workflow.create within proj_abc only — permissions do not extend to other projects or org-level resources.

Where you see it

• API — the Roles tag group covers creating, updating, and deleting custom roles, plus listing and managing role assignments.

See also

• API Keys — authenticate as a user or service account before role assignments take effect.
• Workflows — the resources that role permissions govern.
• Runs — execution records accessible based on actor permissions.