RBAC and permissions
How roles, permissions, groups and scopes decide what each person and token can do in VeloPhex.
Access in VeloPhex is permission-based. A permission allows one operation on one kind of resource. A role is a named set of permissions. A role assignment gives a role to a user or a group, either across the whole tenant or inside one workspace. What a caller may do is the union of every role that applies to it.
How a request is authorized#
- The caller is authenticated (session cookie, personal access token or desktop sign-in, application token, machine token or execution token). Anonymous calls are refused unless an endpoint is explicitly public, such as the health probes.
- The endpoint names the permission it needs, for example
jobs.createto start a job. - The Orchestrator checks the caller's roles at tenant scope and, for workspace resources, at the workspace's scope.
- A tenant or workspace the caller cannot see answers
404, so the response never reveals whether it exists. A missing permission inside a visible tenant answers403.
Every controller action is covered by an automated test that fails the build if an endpoint has no authorization requirement.
Permission strings#
Permissions have the form <resource>.<operation>, with operations view, create, edit and delete, plus a few extra operations such as jobs.cancel. The ones you will use most:
| Area | Permissions |
|---|---|
| Tenant | tenant.view, tenant.edit, dashboard.view |
| Members, groups and roles | users.view, users.edit, users.delete, roles.view, roles.edit, roles.delete |
| Audit, settings and notifications | audit.view, settings.view, settings.edit, notifications.view |
| Machines and Robots | machines.view, machines.edit, machines.delete, robots.view, robots.edit, robots.delete |
| Packages | packages.view, packages.create (publish), packages.edit, packages.delete |
| Credential stores | credential_stores.view, credential_stores.edit, credential_stores.delete |
| Workspaces | folders.view, folders.edit, folders.delete |
| Processes | processes.view, processes.edit, processes.delete |
| Jobs and logs | jobs.view, jobs.create (start), jobs.cancel (cancel and stop), jobs.edit (administrative correction), logs.view |
| Queues | queues.view, queues.edit, queues.delete, queue_items.view, queue_items.create, queue_items.edit, queue_items.delete, queue_item_reviews.edit |
| Triggers and assets | triggers.view, triggers.edit, triggers.delete, assets.view, assets.edit, assets.delete |
Contract names
Some permission strings keep older names because they are part of the API contract: workspaces use folders.* and processes use processes.*. In the web app and in these docs they are called workspaces and processes.
GET /api/v1/permissions returns the full list your Orchestrator knows.
Built-in roles#
Every tenant is provisioned with these roles. You cannot delete them, and you can create your own alongside them.
| Role | Scope | Intended for |
|---|---|---|
| Administrator | Tenant | Every permission in the tenant. Holding it tenant-wide also bypasses workspace membership. |
| Workspace Administrator | Workspace | Full control of one workspace's processes, jobs, queues, triggers and assets. |
| Operator | Tenant | Runs and monitors automations: starts, cancels and corrects jobs, works queue items, reads logs, assets, machines and packages. |
| Viewer | Tenant | Read-only access to tenant resources. Never includes secret values. |
| Automation Developer | Tenant | Everything an Automation User can do, plus managing queues and publishing packages (packages.view, packages.create). |
| Automation User | Workspace | Runs automations in a workspace: starts and cancels jobs, works queue items, reads assets and logs. |
| Everyone | Tenant | Granted to all members: sees the tenant, notifications, and the workspaces, processes and jobs of workspaces the member belongs to. |
Tenants that use the optional QA Hub or Launchpad services also get built-in roles for them (for example QA Hub Administrator or Launchpad Viewer).
Secret values are never returned by any read permission. assets.view shows that a credential exists and its user name, not its password.
Scopes#
- Tenant scope applies the role everywhere in the tenant.
- Workspace scope applies the role only to resources in one workspace (processes, jobs, queues, triggers, assets). Use it to give a team full control of its own workspace without access to others.
A separate platform-administrator policy governs the platform admin area (/admin): tenants, platform users, identity providers, licensing, storage and platform settings. Tenant roles never grant it. A platform administrator can also mark a user as organization administrator, which makes them an Administrator in every tenant without platform rights.
Groups#
Create groups to assign roles once for many people. A group has members and role assignments; each member gets the group's roles. With single sign-on, a group can also be mapped to a group in your identity provider, and SCIM can provision group members. See Users and roles.
| Task | API |
|---|---|
Create a group (users.edit) |
POST /api/v1/tenants/{tenantId}/groups |
Set its members (users.edit) |
PUT /api/v1/tenants/{tenantId}/groups/{groupId}/members |
Set its roles (roles.edit) |
PUT /api/v1/tenants/{tenantId}/groups/{groupId}/roles |
Create a custom role#
Prerequisites: roles.edit in the tenant.
- Open the tenant's roles page, or call
POST /api/v1/tenants/{tenantId}/roles. - Give the role a name and choose its scope (tenant or workspace).
- Select the permissions. Start from the smallest set that does the job.
- Assign it to a user or group:
POST /api/v1/tenants/{tenantId}/role-assignments
Content-Type: application/json
{ "roleId": "…", "userId": "…", "workspaceId": "…" }
Omit workspaceId for a tenant-wide assignment, and use groupId instead of userId to assign to a group.
Verify: call GET /api/v1/tenants/{tenantId}/users/{userId}/effective-access (needs users.view). You should see the new permissions in the user's effective access for that workspace.
Tokens inherit, never exceed#
A personal access token carries a subset of its creator's permissions in one tenant, chosen when it is created. If the creator later loses a permission, the token cannot use it either. A desktop sign-in (Studio and the Assistant) holds the app's fixed set of permissions intersected with yours, checked on every request. An application token holds the permissions chosen when the application was created, never more than its creator held. Execution tokens are limited to the job's own workspace, and machine tokens reach only the Robot API.
Next steps#
- Invite people and assign roles: Users and roles.
- Organize work into Workspaces and tenants.
How a request is authorized
Permission strings
Built-in roles
Scopes
Groups
Create a custom role
Tokens inherit, never exceed
Next steps