Custom roles are available on the Enterprise plan.
How custom roles work
Each custom role is built around three concepts:- Base Role (required in the role builder) — Viewer, Explorer, or Developer. Determines the user’s license tier — the kind of work the holder is licensed for; the permissions themselves come from the role’s Global and deployment policies.
- Global permissions — org-wide capabilities such as billing, customization, integrations, and account-wide deployment management.
- Deployment permissions — one or more policies, each targeting “All deployments” or specific deployments.
Browsing roles
To see the list of custom roles, go to Admin → Custom Roles in your Cube account. Click on a role to edit it, or click Add Role to create a new one.Anatomy of a custom role
The role builder uses a two-column layout. The left column (sticky as you scroll) holds the role’s identity and the Create / Update button. The right column (scrollable) holds the permission cards.Name and description
- Name is required and must be unique within the account. The role builder reserves
Admin,Guest,Developer,None, andAll— the API reserves a different set, see Validation. - Description is optional but recommended — it shows up alongside the role on the Custom Roles list and on user profile pages.
Base Role
Every custom role has exactly one Base Role. It determines:- The user’s license tier — Cube infers the tier from the highest Base Role across all of the user’s roles.
- What that tier licenses — the kind of work its holder may do. The Base Role grants no deployment-scoped access on its own, even where a built-in role of the same name does; that comes from the role’s own deployment policies.
Whether the holder may do any of it on a given deployment is a separate question, answered by the role’s own deployment policies — which is what the built-in roles of the same names add:
DeploymentRead, DeploymentAgentRead and DownloadData over every deployment for Viewer and Explorer, nearly every deployment action for Developer, the data-model ones included. Developer’s account-wide deployment management is a third thing again — a Global permission.
So a custom role with Base Role Viewer and no deployment policy is licensed for viewer-level work and reaches no deployment; a Developer-equivalent has to grant the deployment actions itself, which is what Full access (All) is for.
The tier is hierarchical, so a higher one satisfies a requirement for a lower:
- Explorer meets any Viewer requirement.
- Developer meets any Explorer or Viewer requirement.
The Base Role is required. Save is disabled until one is selected.
Auto-bump to Developer
Four deployment-scoped actions sit at every tier: Access deployment (DeploymentRead), Access AI agents (DeploymentAgentRead), Download data (DownloadData) and Access chat history (ChatHistoryRead). Check any other one — for example Edit deployment or Edit data model — and the Base Role is automatically forced to Developer, with the Viewer and Explorer options disabled behind a tooltip:
Selected actions require Developer roleRemoving the elevated action re-enables the lower tiers. This is a rule of the builder, not of the server: nothing rejects a role whose tier is lower than its deployment actions, so a role written through the API keeps whatever tier it was sent with.
Global permissions
Global permissions are org-wide. Check any number of them on the Global permissions card:Deployment permissions
Deployment permissions are scoped to specific deployments. A custom role can have any number of deployment policies, each represented as its own card. Click Add deployment policy to add another card. Each card has two sections:Scope
Choose which deployments the policy applies to:- All deployments — the policy covers every deployment in the account, including ones added later.
- Specific deployments — pick deployments from a searchable multi-select picker.
Actions
Either grant Full access (a shortcut that enables every current and future deployment-scoped permission) or pick granular actions:
When Full access is checked, the granular checkboxes appear checked and disabled — granting Full access today also covers any deployment-scoped permissions added in the future.
Walkthroughs
Create a Viewer with read access to all deployments
A common pattern: someone who consumes dashboards and chats but never edits anything.1
Open the role builder
Go to Admin → Custom Roles and click Add Role.
2
Name it
Set the Name to, e.g.,
Org Viewer.3
Pick the Base Role
Select Viewer.
4
Add a deployment policy
Click Add deployment policy, leave Scope on All deployments, and check Access deployment and Access AI agents. The Base Role carries neither; Access AI agents is what Analytics Chat needs, and both are exempt from the auto-bump, so the role stays a Viewer.
5
Save
Click Create.
Create an Explorer for a single deployment
For an analyst who works in one deployment.1
Set up the basics
Name the role (e.g.,
Marketing Analyst) and pick Explorer as the Base Role.2
Scope the policy
Add a deployment policy, switch Scope to Specific deployments, and pick the relevant deployment(s) from the picker.
3
Pick actions
Check Access deployment so the user can open the deployment, and Download data if they should be able to export query results. Leave the actions outside the four exempt ones alone — Access query history, for instance, forces the Base Role to Developer, so adding one here costs you the Explorer this walkthrough is for.
4
Save
Click Create.
Create a Developer with Full access to specific deployments
For a data engineer who owns a subset of deployments end-to-end.1
Set up the basics
Name the role (e.g.,
Sales Domain Owner).2
Add the deployment policy
Add a deployment policy, switch Scope to Specific deployments, pick the relevant deployments, and check Full access.
3
Confirm the auto-bump
The Base Role automatically switches to Developer and the Viewer/Explorer radios are disabled.
4
Save
Click Create.
Assigning roles to users
To assign a custom role to a user:- Navigate to Admin → Users.
- Either change the role from the dropdown in the users table, or click into the user’s profile page.
- Add one or more custom roles. Multiple roles stack — the user holds the union of permissions.
Validation
These are the role builder’s rules, enforced client-side before it submits; the API validates differently — see Managing roles through the API below:- Name is required and must be unique. Reserved names (
Admin,Guest,Developer,None,All) are rejected. The API reserves a different set — every built-in role name, which includesAIBIDeveloper,AIBIUser,AIBIViewer,D3UserandEmbedUser, but notNoneorAll; seePOST /api/v1/roles. - Base Role is required — Save is disabled until one is picked, and an inline error appears if you try to submit without one.
- A deployment policy with no actions selected is silently dropped on save (treated as a no-op).
- A deployment policy with Specific deployments scope but no deployments selected is also dropped on save.
Managing roles through the API
Custom roles can also be created, updated and assigned over the REST API, so a team that provisions deployments from CI can grant access in the same pipeline instead of finishing in the console. Every call below needs a token that authenticates as a user with the admin role. The API takes the wire format — a flat list of policies — rather than the builder’s cards: the Base Role is aGlobal policy naming the tier, and each deployment policy card is one Deployment policy.
1
Create the deployment
POST /build/api/v1/deployments returns the new deployment, including its numeric id.2
Create a role scoped to it
POST /api/v1/roles, with that id as a string in the Deployment policy’s resources:"resources": ["All"] covers every deployment and "actions": ["All"] is the Full access shortcut, as in the builder. Deployment ids are checked for shape, not existence: a slug or a name is rejected, but an id whose deployment has since been deleted is kept and simply grants nothing. The response carries the role’s id.Unlike the builder, which drops an incomplete policy on save, the API rejects one with 400 if it has no actions or names no resources. (An empty policies list is fine — that is a role granting nothing yet.) Nothing here checks the tier against the actions, so a tier below the one the builder’s auto-bump would have forced yields a role the builder would not have let you save — pick the covering tier anyway if you want the role to round-trip through the console.Role names are unique, so re-running this step for a role that already exists answers 409 rather than creating a second one. The list endpoint has no lookup by name, so a pipeline treating 409 as “already provisioned” has to page GET /api/v1/roles and match on name to recover the id before it can PUT.3
Assign it
PUT /api/v1/roles/{roleId}/users/{userId}. It is idempotent, and DELETE on the same path takes the role away again.GET, PUT and DELETE /api/v1/roles/{roleId} read, update and remove a role; PUT updates only the fields present in the body, and sending policies replaces them outright rather than merging — so read the role first if you mean to add a policy, omit policies to leave them untouched, and send [] to clear them. Renaming to a name another role already holds answers 409, so omit name too unless you mean to change it. DELETE also drops every assignment of the role, from users and from groups, so everyone holding it loses what it granted. These three endpoints cover your custom roles only: a built-in role’s id answers 404 on all three.
Assignment is the exception — PUT /api/v1/roles/{roleId}/users/{userId} resolves built-in roles as well as custom ones, though their ids are neither published nor returned by GET /api/v1/roles, so in practice it is the roles you created that you assign. Cube’s Admin role is not among the ones it resolves: its id returns 404, so assignment cannot hand out the built-in Admin role. That is a property of assignment alone — POST /api/v1/roles accepts a Global policy carrying account-wide actions such as DeploymentsManage or AuditLogManage, so a custom role can grant much of what Admin does. Only an administrator can call any of this.
Reference: action catalog
This section lists every action the role builder exposes. The internal action names match the names shown in the audit log.POST /api/v1/roles accepts a wider set than the builder renders — see the actions enum on POST /api/v1/roles for the full list.