UI Permissions and Permission Sets
UI permissions control which sections of the Promethium interface are visible to a user and which actions they can perform. This page explains how permissions work, what each permission controls, and how to design access for the different user types in your organization.
UI permissions control what a user can see and do in the interface — which pages appear, which buttons are enabled, and which actions are available. They do not control which specific data objects (tables, datamaps, answers) the user can view or query. That is governed by Data Authorization access levels (Viewer, Editor, Owner). See Data Authorization for details.
How UI Permissions Work
Permissions are grouped into Permission Sets. A Permission Set is a named collection of permissions that can be attached to a Role. When a user is assigned a Role, they inherit all the permissions in every Permission Set that Role includes. A user with multiple roles receives the union of all permissions across all roles.
When a user logs in, Promethium resolves their full permission list and delivers it to the browser. Every guarded interface element — navigation items, buttons, action menus — checks this list at render time. If the required permission is absent, the element is hidden or disabled entirely. Users never see a lock icon or error for a feature they cannot access; it simply does not appear.
Key behaviors to understand:
- Permission changes take effect after the user re-logs in — no code deployment or server restart is needed.
- Removing a permission hides the corresponding UI element. The backend also independently enforces the same permissions — a user cannot bypass the restriction by calling the API directly.
- Each top-level navigation section is controlled by an
access_*_functionalitygate permission. Without the gate, the entire section is invisible. The gate alone grants navigation access only — it does not automatically grant the ability to create, manage, or administer within that section. - To give read-only access to a section, grant only the gate permission. To allow management actions, add the corresponding
manage_*orcreate_*permissions.
Permission Reference by UI Section
The sections below map every UI area to the permissions that control it. Use this as your guide when deciding what to include in a permission set.
Navigation Access Gates
These are the top-level permissions. Each one controls whether an entire section appears in the navigation. Without the gate, the user has no visibility into that section at all.
| Permission Key | What disappears without it | Who typically needs it |
|---|---|---|
access_data_explorer_functionality | Data Explorer — browsing and searching registered tables, views, and datamaps | All users who need to discover or query data |
access_answer_functionality | Answer Builder and the Answers list | Analysts and anyone using AI-powered queries |
access_datamap_functionality | Data Prep / Datamap editor | Data engineers and stewards who build data models |
access_datasource_functionality | Data Sources management page | Engineers and admins managing data connections |
access_marketplace_functionality | Marketplace — browsing and managing published data products | Anyone who needs to discover, publish, or approve data products |
access_system_dashboard_functionality | System Dashboard with usage analytics and query history widgets | Users who need visibility into platform activity |
access_project_functionality | Projects section — dbt project list and editor | Engineers working with dbt transformation projects |
access_tenant_management_functionality | Tenant Management — users, roles, permissions, audit, domains, policies, contracts | Administrators only |
access_job_management_functionality | Job Manager — scheduled job list and configuration | Users who create and manage scheduled jobs |
access_system_management_functionality | System Management — platform-level settings | Platform administrators |
access_cluster_management_functionality | Cluster Management — compute cluster configuration | Infrastructure administrators |
access_system_credentials_functionality | System Credentials — stored API keys and connection credentials | Administrators managing stored credentials |
System Dashboard
access_system_dashboard_functionality opens the System Dashboard page. The dashboard is composed of individual widgets — each widget requires its own permission to populate. Without the widget permission, that widget does not render.
| Permission Key | Widget shown | What the user sees |
|---|---|---|
view_used_table | Most Used Tables and Datamaps | Charts showing which tables and datamaps have been queried most recently |
view_used_datasource | Used Data Sources | Statistics on data source query activity |
view_connected_datasource | Connected Data Sources | List of currently connected data sources and their status |
view_recent_answer | Most Used Answers | Recently accessed or frequently used answers |
view_execution | Executions | Query execution statistics and Trino query history |
Data Explorer
access_data_explorer_functionality opens the Data Explorer. Which tables, views, and datamaps the user can see within the Explorer is determined by their Data Authorization access level — not by permission set keys.
The only action within Data Explorer requiring a specific permission is:
| Permission Key | What the user can do | When to grant |
|---|---|---|
edit_endorsement | Add or remove endorsements on tables and datamaps | Grant to data stewards and curators responsible for certifying data quality |
Datamaps
access_datamap_functionality opens the Datamap editor. Viewing, editing, deleting, and sharing existing datamaps, tables, and views is controlled by the user's Data Authorization access level — no permission set key is needed for those actions.
| Permission Key | What the user can do | When to grant |
|---|---|---|
create_datamap | Create a new datamap from scratch or from a data source | Grant to data engineers and stewards who build semantic data models |
Answers
access_answer_functionality opens the Answers page and Answer Builder. Viewing, editing, deleting, and sharing existing answers is controlled by Data Authorization — no permission set key is needed for those actions.
| Permission Key | What the user can do | When to grant |
|---|---|---|
create_answer | Start a new analysis — opens the Analyse flow and enables saving a new answer | Grant to analysts and any user who needs to create or run AI-powered queries |
The + New Analysis button is controlled by the create_answer permission, not by a user's Data Authorization access level (Viewer, Editor, Owner). A user with create_answer can start a new analysis regardless of their access level on other existing answers. Data Authorization access levels apply to saved answer objects: Viewer can open and run an existing answer, Editor can modify and publish it, Owner can delete it.
Marketplace
access_marketplace_functionality opens the Marketplace. Within it, three permissions control what a user can do:
| Permission Key | What the user can do | When to grant |
|---|---|---|
view_marketplace | Browse and view all published Marketplace listings | Grant to any user who needs to discover and use published data products |
publish_marketplace | Submit a datamap or answer for Marketplace publication | Grant to data engineers and stewards responsible for publishing curated data products |
approve_marketplace | Review and approve or reject Marketplace publication requests | Grant to data governance leads who own the approval workflow. The approving user must also have Data Authorization access to the underlying datamap and answer — without it, the approval will fail with an error. Users with the data_admin role have unconstrained access. Users without data_admin need access assigned via domain grouping, role assignment, or direct user assignment. |
Tenant Management
access_tenant_management_functionality opens the Tenant Management section. Read-only access to users, roles, and domains is available to all users by default. The permissions below control the ability to create, edit, and delete within each sub-section.
| Permission Key | What the user can do | When to grant |
|---|---|---|
manage_user | Create, edit, and delete users; manage role assignments | Grant to administrators responsible for user lifecycle management |
manage_role | Create, edit, and delete roles; manage which permission sets are attached | Grant to administrators responsible for role configuration |
view_permission_set | View the Permission Sets list and contents | Grant to administrators who audit permission configurations |
manage_permission_set | Create, edit, and delete permission sets | Grant to administrators responsible for permission set design |
view_audit_logs | View the Audit Logs tab — a full history of user and system actions | Grant to compliance, security, and operations personnel |
manage_domain | Create, edit, and delete domains | Grant to data administrators who organize data into domains |
view_policy | View the Policies list and individual policy details | Grant to administrators and compliance teams who review data policies |
manage_policy | Create, edit, and delete data policies | Grant to data governance leads who define compliance policies |
view_contract | View the Contracts list and individual contract details | Grant to users who need to review data contracts |
manage_contract | Create, edit, and delete data contracts | Grant to data governance leads who define and maintain data contracts |
manage_data_access_control | Access the Data Access Control UI; configure column masking, row-level security, and data access assignments | Grant to data administrators who manage data security policies. Enabling this permission automatically includes manage_role, manage_domain, and manage_user. |
Projects
access_project_functionality opens the Projects section for dbt transformation work.
Project access
| Permission Key | What the user can do | When to grant |
|---|---|---|
create_project | Create a new dbt project configuration | Grant to leads who set up new projects |
clone_project | Clone an existing project from a Git repository | Grant alongside create_project for engineers working from templates |
Project workflow
| Permission Key | What the user can do | When to grant |
|---|---|---|
publish_drafts | Publish draft models from the project catalog | Grant to engineers responsible for promoting changes |
approve_drafts | Approve draft model submissions from other users | Grant to project leads and code reviewers |
perform_git_actions | Access the Git Actions tab; commit, push, and pull changes | Grant to engineers who manage version control |
create_workspace | Create new workspaces within a project | Grant to project administrators who provision environments |
Project execution
| Permission Key | What the user can do | When to grant |
|---|---|---|
execute_sql_commands | Run SQL queries in the project SQL editor | Grant to engineers and analysts who test and run queries |
execute_dbt_commands | Run dbt build and compile commands | Grant to data engineers who execute dbt transformations |
preview_query_data | Preview query results | Grant to any project user who needs to verify query output |
download_query_data | Download query results as CSV or Excel | Grant to users who need to export data for offline analysis |
Project model editing
| Permission Key | What the user can do | When to grant |
|---|---|---|
add_model | Create new SQL model files in the project file tree | Grant to engineers who add new models |
edit_model | Edit SQL content in model files | Grant to engineers who contribute to or maintain models |
enable_select_all_columns_in_model | Use SELECT * in model SQL | Grant only when a project explicitly requires wildcard column selection |
Designing Access for Your Users
A well-designed permission set answers two questions for each user type: which sections should be visible, and which actions should be enabled within those sections. Object-level access (who can read, edit, or delete specific tables, datamaps, and answers) is handled separately through Data Authorization.
Two-step process:
- Start with the access gate — Grant the
access_*_functionalitypermission for each section the user needs. Without the gate, the section is completely invisible. - Add action permissions — Grant
create_*for object creation,manage_*for administrative control. Do not add permission set keys for view, edit, delete, or share on individual objects — use Data Authorization access levels for those.
Quick reference:
| Goal | Permissions to grant |
|---|---|
| User can browse the Data Explorer but only view data they are authorized to see | access_data_explorer_functionality |
| User can create and manage datamaps | access_datamap_functionality + create_datamap |
| User can create and run AI analyses | access_answer_functionality + create_answer |
| User can register and configure data sources | access_datasource_functionality + manage_datasource |
| User can publish answers to the Marketplace | access_answer_functionality + access_marketplace_functionality + create_answer + publish_marketplace |
| User can manage users and roles | access_tenant_management_functionality + manage_user + manage_role |
| User can configure column masking and row-level security | access_tenant_management_functionality + manage_data_access_control |
Standard Permission Sets
Promethium ships with six built-in permission sets designed around common user personas. These are starting points — you can create custom permission sets tailored to your organization's structure.
Changes to a permission set take effect for all users and roles assigned to it after they re-log in.
Tenant Admin
Manages users, roles, and permission sets across the tenant. Does not have access to data assets or platform configuration.
Best for: IT administrators, HR operations, access managers.
| Module access | Action permissions |
|---|---|
access_tenant_management_functionality | manage_role, manage_user, view_audit_logs, manage_permission_set |
access_marketplace_functionality | view_marketplace |
Data Admin
Full platform access — manages data sources, domains, data access control, and all data assets. Intended for users responsible for the overall data platform.
Best for: Data platform owners, chief data officers, data governance leads.
| Module access | Action permissions |
|---|---|
access_answer_functionality | create_answer |
access_system_dashboard_functionality | view_used_table, view_used_datasource, view_connected_datasource, view_recent_answer, view_execution |
access_tenant_management_functionality | manage_domain, manage_data_access_control, manage_policy, manage_contract, view_permission_set |
access_data_explorer_functionality | edit_endorsement |
access_datasource_functionality | manage_datasource |
access_datamap_functionality | create_datamap |
access_project_functionality | clone_project, create_project, publish_drafts, approve_drafts, perform_git_actions, create_workspace, execute_sql_commands, preview_query_data, download_query_data, execute_dbt_commands, add_model, edit_model, enable_select_all_columns_in_model |
access_marketplace_functionality | view_marketplace, publish_marketplace, approve_marketplace |
| System gates | access_job_management_functionality, access_system_management_functionality, access_cluster_management_functionality, access_system_credentials_functionality |
Data Engineer
Builds and manages data pipelines, datamaps, and data sources. No administrative or governance capabilities.
Best for: Data engineers and analytics engineers who build and maintain data assets.
| Module access | Action permissions |
|---|---|
access_answer_functionality | create_answer |
access_system_dashboard_functionality | view_used_table, view_used_datasource, view_connected_datasource, view_recent_answer, view_execution |
access_data_explorer_functionality | edit_endorsement |
access_datasource_functionality | manage_datasource |
access_datamap_functionality | create_datamap |
access_marketplace_functionality | view_marketplace |
Data Steward
Curates and governs data assets; manages Marketplace content. No data source or user administration.
Best for: Data stewards responsible for data quality, metadata accuracy, and marketplace governance.
| Module access | Action permissions |
|---|---|
access_system_dashboard_functionality | view_used_table, view_used_datasource, view_connected_datasource, view_recent_answer, view_execution |
access_data_explorer_functionality | edit_endorsement |
access_datasource_functionality | manage_datasource |
access_marketplace_functionality | view_marketplace, publish_marketplace, approve_marketplace |
Data Explorer Permission Set
Explores data and works with data assets. No management or administration capabilities.
Best for: Data analysts who explore datasets and run queries for analysis.
| Module access | Action permissions |
|---|---|
access_system_dashboard_functionality | view_used_table, view_used_datasource, view_connected_datasource, view_recent_answer, view_execution |
access_data_explorer_functionality | edit_endorsement |
access_marketplace_functionality | view_marketplace |
Business User
Consumes data products and published analyses. Focused on discovery and consumption, not creation or management.
Best for: Business analysts and end users who use existing data products.
| Module access | Action permissions |
|---|---|
access_system_dashboard_functionality | view_used_table, view_used_datasource, view_connected_datasource, view_recent_answer, view_execution |
access_data_explorer_functionality | edit_endorsement |
access_marketplace_functionality | view_marketplace |
Managing Permission Sets
Viewing permission sets
The Permission Sets section within Tenant Management lists all permission sets in your tenant. Each entry shows the permission set name, the number of permissions it contains, which roles include it, and the last modification timestamp. You can search and filter by name.
Creating a custom permission set
In the Permission Sets section, use the creation interface to build a permission set from the permission tree. Permissions are organized by functional area (e.g., access_data_explorer_functionality, access_tenant_management_functionality). You can select permissions individually or by entire functional groups.
Editing a permission set
Open any permission set to modify its contents. Add or remove individual permissions from the tree. Changes take effect for all assigned users and roles after they re-log in.
Deleting a permission set
A permission set can only be deleted if it is not currently assigned to any role. Remove it from all role configurations first, then delete it.
Best Practices
- Least privilege — Grant only the permissions users need to perform their day-to-day activities. A user who does not need to create datamaps should not have
create_datamap, even if it seems harmless — it reduces surface area for mistakes. - Use access gates to define scope — If a user should not be working in a section at all, do not grant the gate. A user who cannot see the Projects section cannot accidentally affect dbt pipelines.
- Separate roles by function — Design distinct roles for administrators, engineers, stewards, and consumers rather than sharing a single broad role. This makes it easier to adjust access as responsibilities change.
- Use Data Authorization for object-level access — Do not try to replicate object-level read/write/delete control through permission set keys. Permission sets control feature access; Data Authorization controls data access. Mixing the two creates confusion and maintenance burden.
- Audit periodically — Review role assignments and permission set contents regularly. Users change roles; permission sets can drift. The Audit Logs (available to users with
view_audit_logs) provide a history of permission changes.
For configuring how users access specific data objects, see Data Authorization.