> ## 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. # Create a custom role **🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role. Creates a role and returns it with the `id` to assign it by. Role names are unique, so recreating one that already exists answers `409`. To scope the role to specific deployments, send a `Deployment` policy whose `resources` are the deployment ids as strings. A role usually also needs a `Global` policy naming the holder's license tier — `AIBIView`, `AIBIExplore` or `AIBIDevelop` — which is what the console calls the role's Base Role. Pick a tier that covers the deployment actions you grant: the console forces Developer (`AIBIDevelop`) for every deployment action except `DeploymentRead`, `DeploymentAgentRead`, `DownloadData` and `ChatHistoryRead`, so a lower tier here produces a role its role builder would not have let you save: ```json { "name": "team-analytics", "policies": [ { "resourceType": "Global", "actions": ["AIBIDevelop"], "resources": ["All"] }, { "resourceType": "Deployment", "actions": ["DeploymentRead", "SchemaRead", "SqlRunnerRead"], "resources": ["1734"] } ] } ``` The tier is **not** required and is **not** derived from the deployment actions: a role sent without one is accepted and simply confers no tier, so a user holding only that role gets the deployment grants and still cannot use the product. That is deliberate — a user holds the union of their roles, so a role that only adds a deployment scope beside another role carrying the tier is valid — but it means nothing warns you. Omit the `Global` policy only when some other role supplies the tier. Note the console does require one on every role it writes, so a role created here without a tier shows an unset Base Role when opened in the role builder. Use `["All"]` as `resources` to cover every deployment, and `"All"` as the single action for full access to the deployments in scope. A policy is rejected when it grants no action, when it names no resource, or when a `Deployment` resource is not a deployment id — pass the numeric id returned by POST /build/api/v1/deployments, not a slug or a name. Ids are checked for shape, not existence, so an id whose deployment was since deleted is kept and simply grants nothing. ## OpenAPI ````yaml /api-reference/api.yaml post /api/v1/roles openapi: 3.1.0 info: title: Cube Platform API version: 1.0.0 description: >- Programmatically manage Cube: deployments and everything scoped to them (environments, folders, reports, workbooks, notifications, workspace, and agents), plus account-level users, groups, policies, embedding, and AI settings. Data-model authoring, dev mode, branches, and uploads live under /build/api/v1 — same host and token, routed to the build pods. servers: - url: https://{tenant}.cubecloud.dev description: Your tenant host. Replace the whole host if you use a custom domain. variables: tenant: default: your-tenant description: Your Cube tenant subdomain security: - bearerAuth: [] tags: - name: Deployments - name: Deployment Creation - name: Environments - name: Env Variables - name: Regions - name: Data Model - name: Data Model Uploads - name: GitHub - name: GitHub Connection - name: dbt Sync - name: Databricks Metric View Publication - name: Databricks Metric View Integration - name: Folders - name: Reports - name: Workbooks - name: Dashboard Exports - name: Notifications - name: Workspace - name: Users - name: Users Admin - name: Roles - name: User Attributes - name: User Attribute Values - name: Tenant Settings - name: OAuth Integrations - name: User OAuth Tokens - name: OIDC Token Configs - name: App Theme - name: Embed - name: Embed Tenants - name: Dashboard Embed Access - name: Usage Analytics - name: OpenAPI Spec paths: /api/v1/roles: post: tags: - Roles summary: Create a custom role operationId: createRole requestBody: content: application/json: schema: $ref: '#/components/schemas/RoleCreateBody' description: RoleCreateBody required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/Role' description: '' '400': description: >- The name is one of the built-in role names, or a policy grants no action, names no resource, or scopes a `Deployment` to something that is not a deployment id. '409': description: A role with that name already exists. components: schemas: RoleCreateBody: properties: description: oneOf: - maxLength: 255 type: string - type: 'null' name: description: >- Unique role name. Cannot be one of the built-in role names, which are rejected with `400`: `Admin`, `Developer`, `AIBIDeveloper`, `D3User`, `AIBIUser`, `AIBIViewer`, `Guest`, `EmbedUser`. (The console additionally refuses `None` and `All` in its own role builder; those are accepted here.) maxLength: 255 minLength: 1 type: string policies: description: >- What the role grants. Scope a policy to specific deployments by setting `resourceType` to `Deployment` and listing the deployment ids — as returned by POST /build/api/v1/deployments — in `resources`, or `["All"]` for every deployment. An empty `policies` list is accepted and creates a role that grants nothing yet; an individual policy with no actions, or none naming a resource, is rejected. items: $ref: '#/components/schemas/Policy' maxItems: 200 type: array required: - name - policies type: object Role: properties: description: oneOf: - type: string - type: 'null' id: type: integer name: type: string policies: items: $ref: '#/components/schemas/Policy' type: array required: - id - name - policies type: object Policy: properties: actions: items: enum: - All - DeploymentsManage - DeploymentCreate - DeploymentRead - DeploymentUpdate - DeploymentDelete - SecretsManage - DownloadData - PlaygroundRead - SchemaRead - SchemaUpdate - SchemaUpdateDevBranches - APMRead - ChatHistoryRead - PreAggregationBuild - AlertsCreate - AlertsRead - AlertsUpdate - AlertsDelete - AuditLogManage - BillingRead - SqlRunnerRead - DataAssetsRead - DataAssetsManage - CubeNetworkConnect - ReportRead - ReportEdit - ReportManage - WorkbookManage - WorkbookRead - WorkbookEdit - ChatThreadRead - AgentManage - AgentRead - AgentSpaceManage - AgentAdmin - DeploymentAgentRead - OAuthIntegrationsManage - OAuthIntegrationsIssueTokens - McpToolsManage - AIBIDevelop - AIBIExplore - AIBIView - ChartPalettesManage - DashboardThemesManage - AIBIDeveloper - AIBIUser - AIBIViewer - EmbedDeploymentRead - EmbedDashboardRead - FolderRead - FolderEdit - FolderManage type: string type: array resourceType: $ref: '#/components/schemas/PolicyResourceType' resources: items: type: string type: array required: - resourceType - actions - resources type: object PolicyResourceType: enum: - Global - Deployment - Report - ReportFolder - Agent - AgentSpace - Workbook - Dashboard - Folder - ChatThread type: string securitySchemes: bearerAuth: type: http scheme: bearer description: 'Token authentication. Send `Authorization: Bearer `.' ````