> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-pavel-claude-elegant-dirac-88avqw.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom roles
> Define fine-grained custom roles for your organization on the Enterprise plan.
Custom roles are available on the [Enterprise plan](https://cube.dev/pricing).
Cube comes with [default roles][ref-default-roles] (Admin, Developer, Explorer, Viewer) that cover common use cases. When you need finer control — for example, to let a user edit the data model on a single deployment but nothing else — you can define **custom roles** with a tailored set of permissions.
[ref-default-roles]: /admin/users-and-permissions/roles-and-permissions
## How custom roles work
Each custom role is built around three concepts:
1. **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.
2. **Global permissions** — org-wide capabilities such as billing, customization, integrations, and account-wide deployment management.
3. **Deployment permissions** — one or more policies, each targeting "All deployments" or specific deployments.
Permissions stack: a user gets the union of every role assigned to them, so a user with multiple custom roles holds the broadest set of granted permissions.
## 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`, and `All` — the API reserves a different set, see [Validation](#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.
| Base Role | What the tier licenses |
| --------- | ----------------------------------------------------------------------- |
| Viewer | Viewing dashboards and chats. |
| Explorer | Viewer's work, plus creating and editing workbooks and running queries. |
| Developer | Explorer's work, plus editing the data model. |
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](#global-permissions).
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 role
Removing 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](#managing-roles-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:
| Group | Permission | What it grants |
| ------------------------------------ | --------------------------------- | ----------------------------------------------- |
| Audit & Billing | Manage audit log | Access and configure the audit log. |
| Audit & Billing | View billing | View invoices and usage. |
| Customization | Manage chart palettes | Create and edit org-wide chart palettes. |
| Customization | Manage dashboard themes | Create and edit org-wide dashboard themes. |
| Integrations / Network | Manage OAuth integrations | Configure OAuth integrations and clients. |
| Integrations / Network | Issue OAuth tokens | Mint OAuth tokens for integrations. |
| Deployment management (account-wide) | Manage deployments (account-wide) | Create and list deployments across the account. |
### 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:
| Group | Permission | What it grants |
| ----------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| General | Access deployment | Foundation permission required to access the deployment at all. A custom role with Base Role **Viewer** needs this to open the deployment; the built-in Viewer already has it from its own deployment policy. |
| General | Edit deployment | Modify general deployment settings (name, Build & Deploy, Configuration flags, etc.). Does **not** include environment variables, data sources, or other configuration secrets — see **Manage secrets**. |
| General | Delete deployment | Remove the deployment. |
| Configuration & Secrets | Manage secrets | View and edit environment variables, manage data sources (add/edit database connections, including the test-connection step), the Model Configuration card on **Settings → Configuration**, Power BI (XMLA) settings, and restarting dev mode to apply saved environment variable changes. |
| Data Model | View data model | Read data model files and dev branches. |
| Data Model | Edit data model | Edit the data model on any branch, including the main/deploy branch. Allows committing and merging to main, force-syncing main, and starting dev mode against main. |
| Data Model | Edit data model on dev branches | Edit the data model only on non-default branches. Blocks any write that targets the main/deploy branch (including merging to main). |
| Data Model | Access SQL Runner | Open the SQL Runner and execute queries in it. |
| AI | Access AI agents | Use the AI agent in Analytics Chat, workbooks, the IDE, and dashboards. |
| Pre-aggregations | Build pre-aggregations | Trigger pre-aggregation builds (**Build All** and bulk build actions). Withholding it prevents accidental large builds that put Cube Store under pressure. |
| Monitoring | Access query history | View deployment query history, performance, and traces. |
| Monitoring | Access chat history | View other users' chat conversations for the deployment, including Analytics Chat and the Excel/Google Sheets add-in panes (**Admin → Chats History**). It is [exempt from the auto-bump](#auto-bump-to-developer), so a Viewer-tier role can hold it — grant it only to roles that should see other people's conversations. |
| Data Export | Download data | Download query results as CSV from workbooks, Analytics Chat, and published dashboards. The built-in Viewer, Explorer and Developer roles grant it themselves, through their own deployment policies; a custom role does not inherit that from its Base Role, so check it here if the role needs it. See [Data download controls][ref-data-download-controls]. |
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.
**Access deployment** (`DeploymentRead`) and **Download data** (`DownloadData`) are exempt from the [auto-bump](#auto-bump-to-developer) because a Viewer-tier role has to be able to hold them — opening a deployment and downloading from it are viewer-level work. That section lists the full set of exempt actions.
[ref-data-download-controls]: /admin/users-and-permissions/roles-and-permissions#restricting-data-downloads
## Walkthroughs
### Create a Viewer with read access to all deployments
A common pattern: someone who consumes dashboards and chats but never edits anything.
Go to **Admin → Custom Roles** and click **Add Role**.
Set the **Name** to, e.g., `Org Viewer`.
Select **Viewer**.
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](#auto-bump-to-developer), so the role stays a Viewer.
Click **Create**.
### Create an Explorer for a single deployment
For an analyst who works in one deployment.
Name the role (e.g., `Marketing Analyst`) and pick **Explorer** as the Base Role.
Add a deployment policy, switch **Scope** to **Specific deployments**, and pick the relevant deployment(s) from the picker.
Check **Access deployment** so the user can open the deployment, **Access AI agents** for Analytics Chat, and **Download data** if they should be able to export query results — all three are [exempt from the auto-bump](#auto-bump-to-developer), so the role stays an Explorer. Leave every other action alone — **Access query history**, for instance, forces the Base Role to Developer, so adding one here costs you the Explorer this walkthrough is for.
Click **Create**.
### Create a Developer with Full access to specific deployments
For a data engineer who owns a subset of deployments end-to-end.
Name the role (e.g., `Sales Domain Owner`).
Add a deployment policy, switch **Scope** to **Specific deployments**, pick the relevant deployments, and check **Full access**.
The Base Role automatically switches to **Developer** and the Viewer/Explorer radios are disabled.
Click **Create**.
## Assigning roles to users
To assign a custom role to a user:
1. Navigate to **Admin → Users**.
2. Either change the role from the dropdown in the users table, or click into the user's profile page.
3. Add one or more custom roles. Multiple roles stack — the user holds the union of permissions.
See [Manage users][ref-manage-users] for more.
[ref-manage-users]: /admin/users-and-permissions/manage-users
## Validation
These are the **role builder's** rules, enforced client-side before it submits; the API validates differently — see [Managing roles through the API](#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 includes `AIBIDeveloper`, `AIBIUser`, `AIBIViewer`, `D3User` and `EmbedUser`, but not `None` or `All`; see [`POST /api/v1/roles`][ref-api-create-role].
* **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][ref-api-roles], 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][ref-api-auth] 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 a `Global` policy naming the tier, and each deployment policy card is one `Deployment` policy.
[`POST /build/api/v1/deployments`][ref-api-create-deployment] returns the new deployment, including its numeric `id`.
`POST /api/v1/roles`, with that id **as a string** in the `Deployment` policy's `resources`:
```json theme={"dark"}
{
"name": "team-analytics",
"policies": [
{
"resourceType": "Global",
"actions": ["AIBIDevelop"],
"resources": ["All"]
},
{
"resourceType": "Deployment",
"actions": ["DeploymentRead", "SchemaRead"],
"resources": ["1734"]
}
]
}
```
`"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](#auto-bump-to-developer) 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`.
`PUT /api/v1/roles/{roleId}/users/{userId}`. It is idempotent, and `DELETE` on the same path takes the role away again.
**The Base Role is required in the builder, but the API neither requires nor infers it.** A role sent without a `Global` tier policy is accepted with no error, and a user whose only role is that one holds the deployment grants yet has no license tier — nothing surfaces it until they sign in and cannot use the product. This is deliberate: permissions stack, so a role that only adds a deployment scope beside another role carrying the tier is valid. Omit the `Global` policy only when you know another of the user's roles supplies it.
`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.
[ref-api-roles]: /api-reference/roles/list-custom-roles
[ref-api-auth]: /api-reference/authentication
[ref-api-create-role]: /api-reference/roles/create-a-custom-role
[ref-api-create-deployment]: /api-reference/deployment-creation/create-a-deployment-with-an-empty-starter-project-and-trigger-its-first-build
## Reference: action catalog
This section lists every action the role builder exposes. The internal action names match the names shown in the [audit log][ref-audit-log]. `POST /api/v1/roles` accepts a wider set than the builder renders — see the `actions` enum on [`POST /api/v1/roles`][ref-api-create-role] for the full list.
[ref-audit-log]: /admin/monitoring/audit-log
### Base Role actions (Global)
As a custom role's Base Role, the action sets the license tier and nothing else — neither the deployment-scoped access nor the Global permissions the built-in role of that name holds. See [Base Role](#base-role) for what the tier licenses.
| Internal name | Label |
| ------------- | --------- |
| `AIBIView` | Viewer |
| `AIBIExplore` | Explorer |
| `AIBIDevelop` | Developer |
### Global actions
| Internal name | Label |
| ------------------------------ | --------------------------------- |
| `AuditLogManage` | Manage audit log |
| `BillingRead` | View billing |
| `ChartPalettesManage` | Manage chart palettes |
| `DashboardThemesManage` | Manage dashboard themes |
| `OAuthIntegrationsManage` | Manage OAuth integrations |
| `OAuthIntegrationsIssueTokens` | Issue OAuth tokens |
| `DeploymentsManage` | Manage deployments (account-wide) |
### Deployment-scoped actions
| Internal name | Label |
| ------------------------- | -------------------------------------------------------- |
| `All` | Full access (every current and future deployment action) |
| `DeploymentRead` | Access deployment |
| `DeploymentUpdate` | Edit deployment |
| `DeploymentDelete` | Delete deployment |
| `SecretsManage` | Manage secrets |
| `SchemaRead` | View data model |
| `SchemaUpdate` | Edit data model |
| `SchemaUpdateDevBranches` | Edit data model on dev branches |
| `SqlRunnerRead` | Access SQL Runner |
| `DeploymentAgentRead` | Access AI agents |
| `PreAggregationBuild` | Build pre-aggregations |
| `APMRead` | Access query history |
| `ChatHistoryRead` | Access chat history |
| `DownloadData` | Download data |