Roles and permissions

RunR authorizes every API request against a single permission catalog. Users get permissions through roles: their own role in the organization, the roles of the groups they belong to, and project access — a role on one project only. API tokens carry a subset of their owner's permissions. Platform administrators operate the installation itself.

The same model runs in both editions:

The catalog and the built-in roles are defined in one file: api/config/permissions.php. What each API route requires is listed in api/config/route_permissions.php.

Built-in roles#

Built-in roles are read-only and exist in every organization.

"Every permission of the edition": a single-tenant install has no tenants.residency.manage, billing.view and billing.manage; a multi-tenant install has no git_providers.manage, runtimes.manage, signup.manage and tickets.manage (the platform administrators do that work there). Roles hold the permissions they list plus the ones those include (see the Includes column of the catalog).

Owner and Admin differ only in ownership:

• only owners (and platform administrators) grant or revoke the Owner role;
• the last owner of an organization can be neither demoted nor removed;
• in multi-tenant installs only tenant owners point a new region at their own monitoring endpoints (Prometheus / Loki).

Permission catalog#

Permissions with scope project can also be granted on single projects (see Project access). The Includes column lists the permissions that always come with a permission (added when a role or a token is saved and when it is resolved); they chain: for example env.edit includes env.view, which includes projects.view. A scope marked single-tenant or multi-tenant exists in that edition only.

Projects#

Git & previews#

See Git deploy.

Configuration#

Operations#

Workflows#

Durable workflows.

Sandboxes#

Sandbox API: isolated sandboxes for untrusted code.

Security#

Software supply chain.

Infrastructure#

Images#

Container images and WebAssembly modules uploaded into region registries (Images). Running an uploaded image in a CaaS project, or naming one in a runtime version, needs nothing beyond creating / changing the project or the runtime.

Models#

Data#

Bindings are resources of the organization (Bindings). Attaching, re-prefixing and detaching on a project needs env.edit on that project as well as bindings.manage.

AI agents (MCP)#

AI agents. The tools of the RunR MCP server use the permissions above — an agent can do what its token can do; approving an OAuth client needs tokens.manage.

Organization#

Billing (multi-tenant)#

Support#

Permissions are also Laravel Gate abilities: $user->can('projects.deploy', $project), Gate::authorize('audit.export'), or ->can('audit.view') on a route.

Custom roles#

Users with roles.manage create roles of their own in Settings → Roles: a name, a description and a selection in the permission matrix. Rules:

• a custom role holds only permissions its editor holds — nobody hands out more than they have;
• implied permissions are added automatically;
• deleting a custom role moves its members to the default role and removes the group roles, project grants and SSO role mappings that used it.

Default role#

New members get the organization's default role: users added on the Users page without a role, self-registration, invitations without a role and users created by single sign-on. It is set on the Roles page (PUT /api/roles/default); the installation default is developer (RBAC_DEFAULT_ROLE, with the Helm chart set through extraEnv). The default role is never Owner.

Groups#

Groups (Settings → Groups) bundle members. A group can have an organization-wide role — every member gets it in addition to their own role — and access to single projects. Effective permissions are the union of all roles. Adding someone to a group requires being able to grant the group's roles.

Memberships have a source: manual (added in the console) or sso (kept in sync by SSO group mapping). Adding a member manually makes an SSO membership permanent.

Project access#

The Access tab of a project gives a user or a group a role on that project only. Only the role's project-scoped permissions apply there. Example: a member with the Viewer role organization-wide and the Developer role on project checkout can deploy checkout and only view everything else.

• Members without organization-wide projects.view see only the projects they have access to.
• Whoever creates a project without seeing every project gets the Admin role on it.
• projects.manage_access allows granting roles on the project — roles whose project permissions the granter holds on that project.
• The Owner role is not used for project access.

API tokens#

Personal API tokens (Settings → API Tokens) carry either full access (*) or a selection of permissions:

• a token can only be created with permissions its owner holds (organization-wide or on some project);
• at every request the token is limited to what its owner may do at that moment — changing or removing a member's role limits their tokens immediately;
• tokens optionally expire (expires_at);
• a token created inside a tenant works in that tenant only;
• a token of a platform administrator with a selection of permissions is limited to them: it reaches the routes marked @platform:<permission> when it carries that permission (the billing API — a token with only billing.view or billing.manage is the way to connect a billing system), never the routes marked @platform;
• tokens RunR issues to MCP clients through OAuth (AI agents) are API tokens as well — named <client> (MCP), with the permissions and lifetime approved on the consent page, revocable here like any other.

GET /api/tokens returns the permissions a new token may carry (available_abilities).

SSO group mapping#

Sign-in providers (Settings → Auth Providers, OIDC and SAML) can manage groups and roles:

• Groups claim / attribute — the OIDC claim (from the userinfo response) or SAML attribute that carries the user's groups. When empty, RunR reads groups, the Entra ID group claim (http://schemas.microsoft.com/ws/2008/06/identity/claims/groups) and memberOf.
• Role for new users — the role users created just in time by this provider get; empty = the organization's default role.
• Group mappings — external group → group and/or role, for one provider or every provider. Matching is case-insensitive.

On every SSO sign-in:

1. Every mapped group follows the IdP: the member joins (source sso) when one of their external groups maps to it and leaves when none does. Manual memberships stay.
2. When at least one mapping that applies to the provider (its own or one for every provider) sets a role, the IdP manages the member's organization-wide role: the matching role with the most permissions, else the provider's role for new users, else the organization's default role. Owners keep their role.
3. Just-in-time provisioning (auto_register): a new account becomes a member with the role for new users (or a mapped role). In multi-tenant installs the account is a platform account that joins the tenant; an existing account with the same e-mail joins the tenant instead of being created again.

Platform administrators#

users.is_admin marks the operators of a multi-tenant installation: tenants, quotas, cost configuration, charges and plans, platform regions, impersonation and support across tenants. They pass every permission check (Gate::before) in every tenant, unless they use an API token with a selection of permissions. Routes for them only are marked @platform in the route map; routes marked @platform:<permission> (the billing API) also accept their tokens that carry the permission. Other users have no permissions in the central context (no active tenant).

Enforcement#

• App\Http\Middleware\AuthorizeApiRoute (api middleware group) checks every authenticated API route against config/route_permissions.php, after authentication, tenant identification and route model binding. A route with {project} is checked for that project. A route behind auth:sanctum without a rule is refused (403).
• Policies refine checks inside controllers: ProjectPolicy, GatewayPolicy (gateways belong to their creator; routing a project through one needs projects.update on the project), RolePolicy, GroupPolicy. Updating a project needs env.edit for changed environment variables and projects.update for every other field.
• Tests\Feature\Rbac\RouteAuthorizationTest fails when an API route has no rule, when a rule names an unknown permission or a route that no longer exists, and when a @policy route's controller does not authorize.

For contributors: adding a route or a permission#

Every API route behind auth:sanctum needs a rule — the API refuses unmapped routes (403) and php artisan test tests/Feature/Rbac/RouteAuthorizationTest.php fails on them, and on rules whose route no longer exists. Add the route, then one line to config/route_permissions.php:

'GET audit-events'      => 'audit.view',
'POST projects/{project}/rollback' => 'projects.deploy',   // checked for {project}
'GET reports'           => 'projects.view:any',            // org-wide or on some project
'GET things'            => 'regions.manage|registry.manage', // any of them
'POST things'           => ['regions.manage', 'registry.manage'], // all of them
'GET status'            => '@authenticated',               // any signed-in user
'GET admin/plans'       => '@platform',                    // platform administrators only
'GET billing/charges'   => '@platform:billing.view',       // platform administrators; a token must carry billing.view
'PATCH gateways/{gateway}' => '@policy',                   // the controller authorizes (Policy)

or put ->can('audit.view') on the route. Finer checks inside a controller use the same names: Gate::authorize('env.edit', $project), $request->user()->can('audit.export').

A new permission:

1. one entry in config/permissions.php (group, scope — project when it can be granted on single projects —, implies, edition when it exists in one edition only);
2. the built-in roles that should hold it (Owner and Admin hold everything);
3. a label and a hint in vue/src/locales/en/rbac.js and vue/src/locales/tr/rbac.js (rbac.perm.<name with _>, rbac.permHint.<name with _>) — PermissionCatalogTest checks both;
4. the row in this page's catalog, and the mock catalog of the UI tests (vue/e2e/fixtures/data.ts).

In the console, usePermissionsStore().can('name', projectId) hides what the user cannot do; the API decides either way.

CLI#

runr members, runr roles, runr groups, runr access and runr tokens administer members, roles (including runr roles permissions, the catalog, and runr roles default), groups, project access and API tokens with the permissions listed below (CLI: access control).

API#

A refused request answers 403 with the permission it needs:

{ "message": "You do not have permission to do this (requires projects.deploy).", "permissions": ["projects.deploy"] }

Upgrade from 0.4.x#

The upgrade migrations give every existing user and token what the 0.4.x role or scope stood for. 0.4.x did not enforce two of them: a tenant viewer could change and deploy projects like a member, and API token scopes were stored but not checked. 0.5.0 enforces both — give a viewer who works on projects the Member or Developer role, and a scoped token that has to deploy the scope that allows it (upgrade.md).

Clients that still send 0.4.x scope names when creating a token get the same translation. Migrations: 2026_10_10_000001_create_rbac_tables, 2026_10_10_000002_assign_roles_to_existing_users, 2026_10_10_000003_translate_legacy_token_abilities, Tenancy 2026_10_10_100001_widen_tenant_user_role, AuthProvider 2026_10_10_200001_add_sso_group_mapping, tenant migrations 0040_create_rbac_tables, 0041_create_legacy_member_role, 0042_add_sso_group_mapping. The Helm pre-upgrade job runs all of them (including tenancy:migrate) before the new version serves requests.