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#

  1. 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.
  2. The endpoint names the permission it needs, for example jobs.create to start a job.
  3. The Orchestrator checks the caller's roles at tenant scope and, for workspace resources, at the workspace's scope.
  4. 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 answers 403.

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.

  1. Open the tenant's roles page, or call POST /api/v1/tenants/{tenantId}/roles.
  2. Give the role a name and choose its scope (tenant or workspace).
  3. Select the permissions. Start from the smallest set that does the job.
  4. Assign it to a user or group:
HTTPCopy
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#

How a request is authorized

Permission strings

Built-in roles

Scopes

Groups

Create a custom role

Tokens inherit, never exceed

Next steps