Role API

Role API

Use the Role API endpoints to programmatically create and manage role objects in ThoughtSpot.

Supported operations🔗

API endpointAvailable from

POST /api/rest/2.0/roles/create
Creates a Role.

ThoughtSpot Cloud 9.7.0.cl
ThoughtSpot Software Not available

PUT /tspublic/v1/role/{role_identifier}
Edits the properties of a Role object.

ThoughtSpot Cloud 9.7.0.cl
ThoughtSpot Software Not available

POST /tspublic/v1/role/search
Gets Role objects.

ThoughtSpot Cloud 9.7.0.cl
ThoughtSpot Software Not available

DELETE /tspublic/v1/role/{role_identifier}
Removes a Role object from ThoughtSpot.

ThoughtSpot Cloud 9.7.0.cl
ThoughtSpot Software Not available

Required permissions🔗

  • To create and manage roles, you need ROLE_ADMINISTRATION.

  • To assign roles to a group object, you need GROUP_ADMINISTRATION and ROLE_ADMINISTRATION privileges.

Create a Role🔗

To create a Role, send a POST request to the /tspublic/v1/role API endpoint.

Resource URL🔗

POST /tspublic/v1/role

Request parameters🔗

Form parameterDescription

name

String. Name of the Role. The Role name string must be unique. Make sure the name string length does not exceed 48 characters.

description

String. Description of the Role. Make sure the description text does not exceed 124 characters.

privileges

Array of strings. A JSON array of Role privileges.

Example request🔗

cURL
curl -X POST /
--header 'Content-Type: application/x-www-form-urlencoded' /
--header 'Accept: application/json' /
-d 'name=Role12&privileges=%5BA3ANALYSIS%2CDATAMANAGEMENT%5D' /
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role

Example response🔗

{
  "data": {
    "id": "15e2a628-f3b8-4709-8be2-ccc32365011a",
    "name": "Role_Analyst",
    "description": "Analyst Role",
    "privileges": [
      "DATAMANAGEMENT",
      "A3ANALYSIS"
    ],
    "permission": "MODIFY",
    "author_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "modifier_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "creation_time_in_millis": 1698050499277,
    "modification_time_in_millis": 1698050499277,
    "deleted": false,
    "hidden": false,
    "deprecated": false,
    "external": false,
    "shared_via_connection": false
  }
}

Response codes🔗

HTTP status codeDescription

200

Successful operation

400

Invalid parameter

401

Unauthorized access

403

Forbidden access

500

Internal error

Update a role object🔗

To edit the properties of a Role object, send a POST request to the /tspublic/v1/role API endpoint.

Resource URL🔗

PUT /tspublic/v1/role/{role_identifier}

Request parameters🔗

ParameterTypeDescription

role_identifier

Path parameter

String. GUID of the role object to edit.

name

Form parameter

String. Name of the Role that you want to edit.

description

Form parameter

String. Description of the Role.

privileges

Form parameter

Array of strings. A JSON array of Role privileges.

Example request🔗

cURL
curl -X PUT /
--header 'Content-Type: application/x-www-form-urlencoded' /
--header 'Accept: application/json' /
-d 'name=Role_Analyst&description=Analyst%20Role&privileges=%5BJOBSCHEDULING%5D'/
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/15e2a628-f3b8-4709-8be2-ccc32365011a'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/15e2a628-f3b8-4709-8be2-ccc32365011a

Example response🔗

{
  "data": {
    "id": "15e2a628-f3b8-4709-8be2-ccc32365011a",
    "name": "Role_Analyst",
    "description": "Analyst Role",
    "privileges": [
      "JOBSCHEDULING"
      "DATAMANAGEMENT",
      "A3ANALYSIS"
    ],
    "permission": "MODIFY",
    "author_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "modifier_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "creation_time_in_millis": 1698050499277,
    "modification_time_in_millis": 1698050499277,
    "deleted": false,
    "hidden": false,
    "deprecated": false,
    "external": false,
    "shared_via_connection": false
  }
}

Response codes🔗

HTTP status codeDescription

200

Successful operation

400

Invalid parameter

401

Unauthorized access

403

Forbidden access

500

Internal error

Get role objects🔗

To get Role objects, send a POST request to the /tspublic/v1/role/search API endpoint.

Resource URL🔗

POST /tspublic/v1/role/search

Request parameters🔗

Form parameterDescription

role_identifiers

Array of strings. A JSON array of the GUIDs or names of the Role objects. If no value is specified, the API returns all Role objects.

org_identifiers

Array of strings. A JSON array of Org names or GUIDs. Applicable to instances with Orgs. If no value is specified, the API returns the Roles for the Org context from which the API request is sent.

NOTE: Cluster administrators with the Super admin Role can query Role objects for different Orgs. The cluster administrator can switch to an Org context via an API call to the /tspublic/v1/session/orgs endpoint, and then specify the Org name or ID in the API request.

group_identifiers

Array of strings. A JSON array of group names or GUIDs.

privileges

Array of strings. A JSON array of Role privileges.

Example request🔗

cURL
curl -X POST /
--header 'Content-Type: application/x-www-form-urlencoded' /
--header 'Accept: application/json' /
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/search'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/search

Example response🔗

{
  "data": [
    {
      "id": "298b1cad-44d6-4316-985d-8bdd331c8758",
      "name": "_Can download data",
      "description": "Can download data",
      "privileges": [
        "DATADOWNLOADING"
      ],
      "groups": [
        {
          "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
          "name": "Administrator"
        },
        {
          "id": "280a2235-3721-43fc-aa25-5d33549ecc90",
          "name": "DataDownloader"
        }
      ],
      "permission": "MODIFY",
      "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "creation_time_in_millis": 1698049765805,
      "modification_time_in_millis": 1698049765805,
      "deleted": false,
      "hidden": false,
      "deprecated": false,
      "external": false,
      "shared_via_connection": false
    },
    {
      "id": "aee60b22-9225-4120-8f8c-f094d81a8ced",
      "name": "_Can manage data",
      "description": "Can manage data",
      "privileges": [
        "DATAMANAGEMENT"
      ],
      "groups": [
        {
          "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
          "name": "Administrator"
        }
      ],
      "permission": "MODIFY",
      "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "creation_time_in_millis": 1698049765823,
      "modification_time_in_millis": 1698049765823,
      "deleted": false,
      "hidden": false,
      "deprecated": false,
      "external": false,
      "shared_via_connection": false
    },
    {
      "id": "2c90269e-e09c-433f-b4b5-995564dfad70",
      "name": "_Can share with all users",
      "description": "Can share with all users",
      "privileges": [
        "SHAREWITHALL"
      ],
      "groups": [
        {
          "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
          "name": "Administrator"
        },
        {
          "id": "983ddaab-15cf-4c95-a21e-67383a67b6d1",
          "name": "ShareWithAll"
        }
      ],
      "permission": "MODIFY",
      "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "creation_time_in_millis": 1698049765823,
      "modification_time_in_millis": 1698049765823,
      "deleted": false,
      "hidden": false,
      "deprecated": false,
      "external": false,
      "shared_via_connection": false
    },
    {
      "id": "df1202a2-12c3-4748-9ee2-b2b9a6564618",
      "name": "_Can upload user data",
      "description": "Can upload user data",
      "privileges": [
        "USERDATAUPLOADING"
      ],
      "groups": [
        {
          "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
          "name": "Administrator"
        },
        {
          "id": "314ac3fe-c5e1-4898-9cf7-29d9d455f052",
          "name": "UserDataUploader"
        }
      ],
      "permission": "MODIFY",
      "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "creation_time_in_millis": 1698049765821,
      "modification_time_in_millis": 1698049765821,
      "deleted": false,
      "hidden": false,
      "deprecated": false,
      "external": false,
      "shared_via_connection": false
    },
    {
      "id": "3ca25423-4109-4cbc-aff3-e6310bf03095",
      "name": "_Has spotIQ privilege",
      "description": "Has spotIQ privilege",
      "privileges": [
        "A3ANALYSIS"
      ],
      "groups": [
        {
          "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
          "name": "Administrator"
        },
        {
          "id": "c241143a-0e2b-44b6-9cbc-c2b3cff8c57d",
          "name": "Analyst"
        }
      ],
      "permission": "MODIFY",
      "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "creation_time_in_millis": 1698049765772,
      "modification_time_in_millis": 1698049765772,
      "deleted": false,
      "hidden": false,
      "deprecated": false,
      "external": false,
      "shared_via_connection": false
    },
    {
      "id": "2e3ab92a-d0a6-4d6e-85b5-e6fe44fb8bfa",
      "name": "Super Admin",
      "description": "Role with Super Admin privilege",
      "privileges": [
        "ADMINISTRATION"
      ],
      "groups": [
        {
          "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
          "name": "Administrator"
        }
      ],
      "permission": "READ_ONLY",
      "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
      "creation_time_in_millis": 1698049765821,
      "modification_time_in_millis": 1698049765821,
      "deleted": false,
      "hidden": false,
      "deprecated": false,
      "external": false,
      "shared_via_connection": false
    }
  ]
}

Response codes🔗

HTTP status codeDescription

200

Successful operation

400

Invalid parameter

401

Unauthorized access

403

Forbidden access

500

Internal error

Delete a Role🔗

To delete a Role, send a DELETE request to the /tspublic/v1/role/{role_identifier} API endpoint.

Resource URL🔗

DELETE /tspublic/v1/role/{role_identifier}

Request parameters🔗

ParameterTypeDescription

role_identifier

Path parameter

String. GUID of the role object to delete.

Example request🔗

cURL








curl -X DELETE /
--header 'Accept: application/json' /
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/7c8446d2-d9f9-427e-953c-8ed5abc0a3bb'
















Request URL




https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/15e2a628-f3b8-4709-8be2-ccc32365011a










Example response🔗




If the delete operation is successful, the API returns a 204 response.








204










Response codes🔗


HTTP status codeDescription
200
Successful operation
400
Invalid parameter
401
Unauthorized access
403
Forbidden access
500
Internal error