# Role-based access control > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/rbac # Role-based access control ThoughtSpot administrators can assign granular privileges to users with Role-Based Access Control (RBAC). > **IMPORTANT:** The RBAC feature is turned off by default. To enable this feature on your cluster, contact ThoughtSpot Support. Note that once you enable RBAC, it cannot be disabled. ## Roles and privileges A `Role` is a collection of privileges that determines users' access to ThoughtSpot objects and workflows. Roles can be high-level, like Super Admin, or specific based on your organization’s structure and requirements. When the RBAC feature is enabled on your instance, administrators can grant granular privileges and thus implement fine-grained access control to ThoughtSpot features, objects, and metadata. For example, on ThoughtSpot instances with no RBAC, members of the groups with administration privileges can view and administer users, groups, and roles. With RBAC, you can assign granular privileges and restrict application-wide access only to super admin users. | ThoughtSpot privilege (without RBAC) | ThoughtSpot RBAC Roles | | --- | --- | | _Can administer ThoughtSpot_ This privilege grants administration permissions to manage users and groups on instances that do not have the RBAC feature enabled. | RBAC allows multiple Roles with granular privileges for administration control: - User administration: _Can manage Users_ - Group administration: _Can manage Groups_ - Role administrator: _Can manage Roles_ - Org administration: _Can manage Orgs_ - Authentication administration: _Can manage Authentication_ - Application administration: _Can manage Application settings_ For a complete list of Roles and privileges, see [Role categories and privileges]({{navprefix}}/{{roles}}#_role_privileges). | ## Role assignment Administrators can create a Role with a specific set of privileges and assign this Role to a group via UI or REST API calls. Users inherit Role privileges from the groups to which they are assigned. To assign a Role to a user, administrators must assign the Role to a group and ensure that the intended users are added to this group. > **NOTE:** Roles are unique to an Org and can be created only within the context of an Org. For more information about Role and Group assignment, see [ThoughtSpot Product Documentation](https://docs.thoughtspot.com/cloud/latest/rbac). ## Role categories and privileges The RBAC feature groups access privileges under specific categories for granular access control and ease of use. You can create a role with a specific privilege from any role category and assign it to a group. > **IMPORTANT:** All ThoughtSpot instances include a Super Admin role that provides cluster-wide administration privileges by default. The Super admin user can access all data, create and manage users, Orgs, Groups, and Roles. This privilege should only be granted in exceptional circumstances. ### Admin control Includes Role privileges that allow administrative access to create and manage ThoughtSpot objects such as users, groups, and Roles. | Role type | Privilege | Description | | --- | --- | --- | | Org administration | API: `ORG_ADMINISTRATION` UI: **Can manage orgs** | Applicable to ThoughtSpot instances with Orgs. Users with `ORG_ADMINISTRATION` privilege can create, edit, and delete Orgs. | | User administration | API: `USER_ADMINISTRATION` UI: **Can manage users** | Allows users to create, edit, and manage users via UI or REST API calls. On clusters with Orgs enabled, this Role allows users to perform CRUD operations only within their Org context. It does not grant access to manage users in the `All Orgs` context. | | Group administration | API: `GROUP_ADMINISTRATION` UI: **Can manage groups** | Allows users to create, edit, and manage groups via UI or REST API calls. | | Role administration | API: `ROLE_ADMINISTRATION` UI: **Can manage roles** | Allows users to create, edit, and manage Roles via UI or REST API calls. | | Authentication administration | API: `AUTHENTICATION_ADMINISTRATION` UI: **Can manage authentication** | Allows users to manage authentication and authorization process for ThoughtSpot users. | | Application administration | API: `APPLICATION_ADMINISTRATION` UI: **Can manage application settings** | Provides access to manage cluster-wide application settings, activation and de-activation of features on an instance. | | System monitoring | API: `SYSTEM_INFO_ADMINISTRATION` UI: **Can view system activities** | Allows users to view system activities and monitor health. | | Billing administration | API: `BILLING_INFO_ADMINISTRATION` UI: **Can view billing information** | Allows view access to billing information. | | Trusted authentication control | API: `CONTROL_TRUSTED_AUTH` UI: **Can enable or disable trusted authentication** | Allows users with super admin (`ADMINISTRATION`) or `DEVELOPER` privilege to enable or disable [Trusted authentication]({{navprefix}}/{{trusted-authentication}}) for applications embedding ThoughtSpot content. | | Tag administration | API: `TAGMANAGEMENT` UI: **Can manage tags** | Allows users to create and edit tags. | | Version control with Git | API: `CAN_SETUP_VERSION_CONTROL` UI: **Can set up version control** | Allows users to enable version control for a ThoughtSpot instance or Org. | | Analyst studio | API: `CAN_MANAGE_ANALYST_STUDIO` UI: **Can manage Analyst Studio** | Allows users to manage Analyst Studio for ThoughtSpot users. | | API: `CAN_ACCESS_ANALYST_STUDIO` UI: **Can use Analyst Studio** | Allows access to Analyst Studio features. | > **NOTE:** Analyst Studio is not supported in ThoughtSpot embedded instances. ### Application control The application control role privileges include the following: | Role type | Privilege | Description | | --- | --- | --- | | SpotIQ access | API: `A3ANALYSIS` UI: **Has SpotIQ privilege** | Allows access to the SpotIQ feature in ThoughtSpot. | | Developer | API: `DEVELOPER` UI: **Has developer privilege** | Allows users to access the following features and workflows: - Access **Develop** page and Playground - Embed a ThoughtSpot application page, object, or full experience in an external application - Customize styles for embedded content - Add custom actions to the embedded objects such as Liveboard and visualizations - View and manage security settings for ThoughtSpot embedding. | | Liveboard job administration | API: `JOBSCHEDULING` UI: **Can schedule for others** | Allows users to schedule, edit, and delete Liveboard jobs. | | ThoughtSpot Sync | API: `SYNCMANAGEMENT` UI: **Can manage sync settings** | Allows setting up secure pipelines to external business apps and sync data using ThoughtSpot Sync. | | Spotter access | API: `CAN_USE_SPOTTER` UI: **Can use Spotter** | Allows access to ThoughtSpot Spotter and natural language query and answer generation. | | Spotter administration | API: `CAN_MANAGE_SPOTTER` UI: **Can manage Spotter** | Allows a designated Spotter administrator to manage Spotter’s behavior across the organization. This role provides the following capabilities: - On data models: The user can manage global coaching, manage Spotter memory (including memory from multi-model Liveboards), and delegate coaching access to other users. - Across all Orgs (regardless of data model access): the user can add and manage Spotter instructions. > **NOTE:** The CAN\_MANAGE\_SPOTTER privilege does not grant data model edit access, does not allow editing columns, synonyms, or descriptions, and does not override data access permissions. | | Catalog management | API: `CAN_CREATE_CATALOG` UI: **Can manage catalog** | Allows users to create, edit, and manage a [data connector catalog](https://docs.thoughtspot.com/cloud/latest/catalog-integration). | ### Object access control The `SHAREWITHALL` (**Can share with all users**) Role privilege allows users to share objects with all the users and groups in ThoughtSpot. ### Data control The data control privileges include the following: | Role type | Privilege | Description | | --- | --- | --- | | Data upload | API: `USERDATAUPLOADING` UI: **Can upload user data** | Allows users to upload data to ThoughtSpot. | | Row-level-security (RLS) bypass | API: `BYPASSRLS` UI: **Can administer and bypass RLS** | Allows access to the following operations: - Create, edit, or delete existing RLS rules - Enable or disable Bypass RLS on a Model For more information, see [Row-level security](https://docs.thoughtspot.com/cloud/latest/security-rls). | | Custom calendars | API: `CAN_MANAGE_CUSTOM_CALENDAR` UI: **Can manage custom calendars** | Allows creating, editing, and deleting [custom Calendars](https://docs.thoughtspot.com/cloud/latest/connections-cust-cal). | | Data Connection | API: `CAN_CREATE_OR_EDIT_CONNECTIONS` UI: **Can create/edit Connections** | Allows creating, editing, and managing [connections to external data warehouses](https://docs.thoughtspot.com/cloud/latest/connections). | | Data objects | API: `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` UI: **Can manage data models** | Allows users to create, edit, delete, and manage Models, Tables, and Views. | | Custom variables | API: `CAN_MANAGE_VARIABLES` UI: **Can manage variables** | Allows users to manage formula Variables in the current Org scope. | ### Data download control If RBAC is enabled on your instance, the granular download privileges replace the single `DATADOWNLOADING` privilege. | Role type | Privilege | Description | | --- | --- | --- | | Download visuals | API: `CAN_DOWNLOAD_VISUALS` UI: **Can download visuals** | Allows users to download data in the PDF or PNG file format. | | Data export | API: `CAN_DOWNLOAD_DETAILED_DATA` UI: **Can download detailed data** | Allows users to export data in XLSX or CSV file format. | > **IMPORTANT:** Users who previously did not have DATADOWNLOADING privileges will not be automatically assigned the new download privileges. Administrators can assign them manually. Users who previously had DATADOWNLOADING privileges will automatically be assigned both new privileges - CAN\_DOWNLOAD\_VISUALS and CAN\_DOWNLOAD\_DETAILED\_DATA. ## How to create and assign Roles You can create and assign Roles to a group on the [Admin page of the UI](https://docs.thoughtspot.com/cloud/latest/rbac) or by using the REST API v1 and v2 endpoints. ### REST API v1 endpoints for Role administration and assignment | Operation type | API endpoints | | --- | --- | | CRUD operations | To create, edit, and manage Role objects, use the following endpoints: - [`POST /tspublic/v1/role`]({{navprefix}}/{{roles-api}}#createRole) Create a Role - [`PUT /tspublic/v1/role/{role_identifier}`]({{navprefix}}/{{roles-api}}#editRole) Edit properties of a Role object. - [`POST /tspublic/v1/role/search`]({{navprefix}}/{{roles-api}}#searchRole) Get a list of Role objects - [`DELETE /tspublic/v1/role/{role_identifier}`]({{navprefix}}/{{roles-api}}#deleteRole) Delete a Role object | | Role assignment to groups | - [`POST /tspublic/v1/group/addrole`]({{navprefix}}/{{group-api}}#addRole) Allows group administrators to assign a specific Role to a group - [`/tspublic/v1/group/`]({{navprefix}}/{{group-api}}#create-group) Allows group administrators to assign one or several Roles to a group - [`POST /tspublic/v1/group/removerole`]({{navprefix}}/{{group-api}}#removeRole) Removes the Roles assigned to a group - [`PUT /tspublic/v1/group/{groupid}`]({{navprefix}}/{{group-api}}#update-group) Edit Role associations of a group object | | Object query | To get the details of Roles assigned to a group object, use the following API endpoint: \* [`GET /tspublic/v1/group/`]({{navprefix}}/{{group-api}}#get-users-group) Note that the API response shows the assigned Roles and privileges in the `assignedRoles` and `granularPrivileges` arrays. | ### REST API v2 endpoints for Role administration and assignment | Operation type | Description | | --- | --- | | CRUD operations | - [`POST /api/rest/2.0/roles/create`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fcreate-role) Create a Role. - [`POST /api/rest/2.0/roles/{role_identifier}/update`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fupdate-role) Edit the properties of a Role object. - [`POST /api/rest/2.0/roles/search`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fsearch-roles) Get a list of Role objects - [`POST /api/rest/2.0/roles/{role_identifier}/delete`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fdelete-role) Delete a Role object | | Role assignment to groups | To assign a Role to a group object, use one of the following endpoints: - [`POST /api/rest/2.0/groups/create`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fcreate-user-group) - [`POST /api/rest/2.0/groups/{group_identifier}/update`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group) | | Object query | - [`POST /api/rest/2.0/roles/search`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fsearch-roles) To get Roles assigned to specific groups, specify the name or GUID of the Role in the `group_identifiers` attribute. Similarly, to search for Roles configured in an Org, specify the name or the GUID of the Org in the `org_identifiers` attribute. - [`POST /api/rest/2.0/groups/search`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fsearch-user-groups) To filter group objects assigned to a particular Role, specify the name or GUID of the Role in the `role_identifiers` attribute. - [`POST /api/rest/2.0/users/search`]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fsearch-users) To get user objects that have a particular Role assigned, specify the name or GUID of the Role in the `role_identifiers` attribute. | ## Migrating to RBAC The Role privileges function in the same way as group privileges. When RBAC is enabled, the corresponding group privileges are automatically migrated to Role privileges. For example, if a group has `DATADOWNLOADING` access, the `DATADOWNLOADING` Role privilege will be assigned to the group after RBAC is enabled. Similarly, if a group has `DATAMANAGEMENT` (**Can manage data**) access, the following Role privileges will be assigned to the group: - **Can manage custom calendars** (`CAN_MANAGE_CUSTOM_CALENDAR`) - **Can create/edit Connections** (`CAN_CREATE_OR_EDIT_CONNECTIONS`) - **Can manage data models** (`CAN_MANAGE_WORKSHEET_VIEWS_TABLES`) For granular access, you can create a Role with required privileges and assign it to groups. ## Restore correct privileges on the ALL group when roles are enabled Every ThoughtSpot instance includes a built-in **ALL** group. All users are automatically members of this group. When RBAC is enabled, the ALL group is assigned an **ALL role**. This role always grants the `AUTHORING` privilege, which is required for all users and must remain assigned to the ALL group at all times. In addition to the ALL role, the ALL group may hold other roles that grant the following privileges: - `DATADOWNLOADING` — Allows users to download data from answers and Liveboards. - `USERDATAUPLOADING` — Allows users to upload data from a local file. These privileges are permitted on the ALL group and may be assigned through additional roles depending on your ThoughtSpot instance’s configuration. For users who have inherited unexpected elevated privileges, follow the steps listed below to restore privileges. > **NOTE:** The ALL role is a System role. You must contact ThoughtSpot support to retrieve its GUID. ### Before you begin Before you start, ensure you have: - Administrator privileges on your ThoughtSpot instance. - A valid bearer token for authentication. ### Procedure to unblock the users 1. Retrieve the GUID of the ALL group Call the `POST /api/rest/2.0/groups/search` endpoint and filter by the group name `All`. ```cURL curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/groups/search' \ -H 'Authorization: Bearer {access-token}'\ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ "record_offset": 0, "record_size": 10 }' ``` From the response, locate the `id` field. This is the GUID of the ALL group. ```JSON [ { "id": "", "name": "All", "display_name": "All Group", "system_group": true, ... } ] ``` 2. Retrieve the GUID of the ALL role Contact ThoughtSpot support for retrieving the guid for the ALL role. 3. Restore the ALL role on the ALL group Call the `POST /api/rest/2.0/groups/{group_identifier}/update` endpoint using the ALL group GUID as the path parameter. Use `REPLACE` as the operation type. This replaces the complete list of roles currently assigned to the ALL group with only the ALL role, removing all unexpected role assignments in a single operation. ```cURL curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/groups//update' \ -H 'Authorization: Bearer {access-token}'\ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ "role_identifiers": { "operation": "REPLACE", "role_identifiers": [ "" ] } }' ``` A successful response returns an HTTP `204` status with an empty body.