Security APIs

The Security APIs allow you to share ThoughtSpot objects, such as pinboards and visualizations, with another user or a user group. Any ThoughtSpot user can share objects with another user or user group.

Supported operations

POST /tspublic/v1/security/share
Shares ThoughtSpot objects with another user or user group.

POST /tspublic/v1/security/shareviz
Shares a specific visualization with another user or user group.

GET /tspublic/v1/security/metadata/permissions
Gets object permission details for a specific object type.

GET /tspublic/v1/security/metadata/{id}/permissions
Gets object permission details for a specific object ID.

GET /tspublic/v1/security/effectivepermissionbulk
Gets object permission details for multiple object types and IDs.

To programmatically share ThoughtSpot objects with another user or user group, use the /tspublic/v1/security/share API endpoint.

When you share an object like a pinboard or visualization, a notification with a live link is sent to the user. When the users access this object, they can view the last saved version of the object.

Resource URL

POST /tspublic/v1/security/share

Request parameters

Form parameter Description

type

String. Type of metadata object. Specify one of the following values as a metadata object type:

QUESTION_ANSWER_BOOK to share search answers.
PINBOARD_ANSWER_BOOK to share pinboards.
LOGICAL_COLUMN to share a column of any data object such as tables, worksheets, or views.
LOGICAL_TABLE to share a data object such as a table, worksheet, or view.

id

String. A JSON array of the GUIDs of the objects to be shared.

permission

String. A string with the GUIDs of the user or user group, and the type of access privilege.

The format of the permission string is {"permissions":{"<GUID of the user or user group>":{"shareMode":"<type-of-access>"}}}.
You can provide READ_ONLY or MODIFY access to the objects. With READ_ONLY access, the user or user group can view the shared object, whereas MODIFY access enables users to modify the object.

For example, to provide read-only access to a user with a GUID of 7a9a6715-e154-431b-baaf-7b58246c13dd, specify the string as {"permissions":{"7a9a6715-e154-431b-baaf-7b58246c13dd":{"shareMode":"READ_ONLY"}}}

The following example shows how to set the permission string to provide read-only access to multiple users:

{"permissions": {"e7040a64-7ff1-4ab9-a1b0-f1acac596866": {"shareMode": "READ_ONLY"}, "f7b8f511-317c-485d-8131-26cf084ef47b": {"shareMode": "READ_ONLY"}}}

To remove a user or user group’s access to a shared object, you can set the shareMode in the permission string to NO_ACCESS. For example, if you send a POST request with the permission string as {"permissions":{"7a9a6715-e154-431b-baaf-7b58246c13dd":{"shareMode":"NO_ACCESS"}}}, the user with a GUID of 7a9a6715-e154-431b-baaf-7b58246c13dd cannot access the shared object.

emailshares

String. The email address of the user accounts with whom you want to share the objects.

notify
Optional

Boolean. When set to true, a notification is sent to the users after an object is shared.

message
Optional

String. The message text to send in the notification email.

useCustomEmbedUrls

Boolean. When set to true, ThoughtSpot sends a link with the host application context to allow users to access the shared object from their ThoughtSpot embedded instance.

Example request

cURL

curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'type=PINBOARD_ANSWER_BOOK&id=["237921cc-ebf5-445a-8b7b-15c301f8456e"]&permission={“permissions”:{“237921cc-ebf5-445a-8b7b-15c301f8456e”:{“shareMode”:”READ_ONLY”}}}&emailshares=["tsuser@thoughtspot.com"]&notify=false&useCustomEmbedUrls=true' \
'https://<ThoughtSpot-host/callosum/v1/tspublic/v1/security/share'

Request URL

https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/share

Example response

Response code

204

Response codes

HTTP status code	Description
204	Successful operation
400	Invalid parameter value

HTTP status code

Description

204

Successful operation

400

Invalid parameter value

Share a visualization with another user or user group

If you want to share a specific visualization from a pinboard with another user or user group, use the /tspublic/v1/security/shareviz API. This API lets you share the visualization with specific user IDs and grant a view-only access.

Resource URL

POST /tspublic/v1/security/shareviz

Request parameters

Form parameter Description

Form parameter	Description
`type`	String. Type of the metadata object. The valid value is `PINBOARD_ANSWER_BOOK`.
`pinboardId`	String. The GUID of the pinboard to which the visualization belongs.
`principalids`	String. A JSON array of the GUID of the users with whom you want to share the visualization.
`vizid`	String. The GUID of visualization.
`emailshares`	String. The email address of the user account with whom you want to share the visualization. If no email address is specified, the visualization is shared only with the user IDs specified in `principalids`.
`notify` Optional	Boolean. When set to `true`, a notification is sent to the user after the visualization is shared.
`message` Optional	String. The message text to send in the notification email.
`useCustomEmbedUrls`	Boolean. When set to `true`, ThoughtSpot sends a link with the host application context to allow users to access the shared object from their ThoughtSpot embedded instance.

type

String. Type of the metadata object. The valid value is PINBOARD_ANSWER_BOOK.

pinboardId

String. The GUID of the pinboard to which the visualization belongs.

principalids

String. A JSON array of the GUID of the users with whom you want to share the visualization.

vizid

String. The GUID of visualization.

emailshares

String. The email address of the user account with whom you want to share the visualization. If no email address is specified, the visualization is shared only with the user IDs specified in principalids.

notify
Optional

Boolean. When set to true, a notification is sent to the user after the visualization is shared.

message
Optional

String. The message text to send in the notification email.

useCustomEmbedUrls

Boolean. When set to true, ThoughtSpot sends a link with the host application context to allow users to access the shared object from their ThoughtSpot embedded instance.

Example request

cURL

curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'type=PINBOARD_ANSWER_BOOK&pinboardId=7a9a6715-e154-431b-baaf-7b58246c13dd&principalids=["59481331-ee53-42be-a548-bd87be6ddd4a"]&vizid=e9753523-5de5-41ef-8d8c-b840f0260ea0&emailshares=[tsuser@thoughtspot.com]&notify=true&useCustomEmbedUrls=false' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/shareviz'

Request URL

https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/shareviz

Example response

Response code

204

Response codes

HTTP status code	Description
204	Successful operation
400	Invalid parameter value

HTTP status code

Description

204

Successful operation

400

Invalid parameter value

Get object permission details for a specific object type

ThoughtSpot users can get access to objects through the privileges assigned to the groups to which they belong. This type of object permission is referred to as EFFECTIVE.

Users can also access objects when another user shares a pinboard or answer directly with them, or the user group to which they belong. This type of object permission is referred to as DEFINED.

To get permission details for a specific metadata type and ID, send a GET request to the /tspublic/v1/security/metadata/permissions endpoint.

Resource URL

GET /tspublic/v1/security/metadata/permissions

Request parameters

Parameter Type Description

Parameter	Type	Description
`type`	Query parameter	String. Type of the object. Valid values are: `QUESTION_ANSWER_BOOK` for answers. `PINBOARD_ANSWER_BOOK` for pinboards. `LOGICAL_TABLE` for any data object such as a table, worksheet, or view. `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views.
`id`	Query parameter	String. A JSON array of the GUIDs of the objects.
`dependentshare` Optional	Query parameter	Boolean. Object permission details for the dependent objects. When set to `true`, the API returns the permission details for the dependent objects for the specified GUIDs.
`permissiontype`	Query parameter	String. Valid values are: `EFFECTIVE` for object permissions inherited from group privileges. `DEFINED` for the explicitly defined permissions that a user may have assigned when sharing the specified objects.

type

Query parameter

String. Type of the object. Valid values are:

QUESTION_ANSWER_BOOK for answers.
PINBOARD_ANSWER_BOOK for pinboards.
LOGICAL_TABLE for any data object such as a table, worksheet, or view.
LOGICAL_COLUMN for a column of any data object such as tables, worksheets, or views.

id

Query parameter

String. A JSON array of the GUIDs of the objects.

dependentshare Optional

Query parameter

Boolean. Object permission details for the dependent objects. When set to true, the API returns the permission details for the dependent objects for the specified GUIDs.

permissiontype

Query parameter

String. Valid values are:

EFFECTIVE for object permissions inherited from group privileges.
DEFINED for the explicitly defined permissions that a user may have assigned when sharing the specified objects.

Example request

cURL

curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/metadata/permissions?type=PINBOARD_ANSWER_BOOK&id=%5B%22d084c256-e284-4fc4-b80c-111cb606449a%22%2C%20%2241a39422-2da0-4601-9d4a-59c27181c5f5%22%5D&dependentshare=false&permissiontype=EFFECTIVE'

Request URL

https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/metadata/permissions?type=PINBOARD_ANSWER_BOOK&id=%5B%22d084c256-e284-4fc4-b80c-111cb606449a%22%2C%20%2241a39422-2da0-4601-9d4a-59c27181c5f5%22%5D&dependentshare=false&permissiontype=EFFECTIVE

Example response

If the GET operation is successful, the API returns a response with the permission details for the specified object IDs.

Note that the shareMode property indicates the object-level permission assigned to a given user.
- READ_ONLY indicates view permissions to an object
- MODIFY indicates edit permissions to an object
If the user doesn’t have access to the specified objects, the API returns a 403 unauthorized error.
If the user doesn’t have access to one of the specified objects, the API returns only those objects to which a user has READ_ONLY or MODIFY permissions.

{
  "41a39422-2da0-4601-9d4a-59c27181c5f5": {
    "permissions": {
      "59481331-ee53-42be-a548-bd87be6ddd4a": {
        "topLevelObjectId": "41a39422-2da0-4601-9d4a-59c27181c5f5",
        "shareMode": "READ_ONLY",
        "dependents": [
          {
            "id": "160e1259-5838-4688-a30a-2442b6d5281e",
            "name": "Credit Consumption & Usage, Top 10 Users, This Month",
            "author": "41a39422-2da0-4601-9d4a-59c27181c5f5",
            "type": "QUESTION_ANSWER_BOOK",
            "shareMode": "READ_ONLY",
            "isHidden": true,
            "owner": "41a39422-2da0-4601-9d4a-59c27181c5f5"
          },
          {
            "id": "835ffe9d-78de-4817-a201-4a35385df18c",
            "name": "Monthly Credits Consumed, with Unique Users",
            "author": "41a39422-2da0-4601-9d4a-59c27181c5f5",
            "type": "QUESTION_ANSWER_BOOK",
            "shareMode": "READ_ONLY",
            "isHidden": true,
            "owner": "41a39422-2da0-4601-9d4a-59c27181c5f5"
          }
        ]
      }
    }
  },
  "d084c256-e284-4fc4-b80c-111cb606449a": {
    "permissions": {
      "59481331-ee53-42be-a548-bd87be6ddd4a": {
        "topLevelObjectId": "d084c256-e284-4fc4-b80c-111cb606449a",
        "shareMode": "READ_ONLY",
        "dependents": [
          {
            "id": "a9466299-4e89-4a2f-a1b2-d87337a4afc6",
            "name": "Total Sales by Store",
            "author": "d084c256-e284-4fc4-b80c-111cb606449a",
            "type": "QUESTION_ANSWER_BOOK",
            "shareMode": "READ_ONLY",
            "isHidden": true,
            "owner": "d084c256-e284-4fc4-b80c-111cb606449a"
          },
          {
            "id": "d766e0da-2fa6-4af5-ab44-d86f28326c3a",
            "name": "Total Sales by Product Type",
            "author": "d084c256-e284-4fc4-b80c-111cb606449a",
            "type": "QUESTION_ANSWER_BOOK",
            "shareMode": "READ_ONLY",
            "isHidden": true,
            "owner": "d084c256-e284-4fc4-b80c-111cb606449a"
          }
        ]
      }
    }
  }
}

Response codes

HTTP status code	Description
200	Successful operation
400	Invalid parameter value

HTTP status code

Description

200

Successful operation

400

Invalid parameter value

Get permission details for a specific object ID

To get permission details for a specific object, send a GET request to the /tspublic/v1/security/metadata/{id}/permissions endpoint.

Resource URL

GET /tspublic/v1/security/metadata/{id}/permissions

Request parameters

Parameter Type Description

Parameter	Type	Description
`type`	Query parameter	String. Type of the object. Valid values are: `QUESTION_ANSWER_BOOK` for answers. `PINBOARD_ANSWER_BOOK` for pinboards. `LOGICAL_TABLE` for any data object such as a table, worksheet, or view. `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views.
`id`	Path parameter	String. The GUID of the object to query.
`dependentshare` Optional	Query parameter	Boolean. Object permission details for the dependent objects. When set to `true`, the API returns the permission details for the dependent objects for the specified GUID.
`permissiontype`	Query parameter	String. Valid values are: `EFFECTIVE` for object permissions inherited from group privileges. `DEFINED` for the explicitly defined permissions that a user may have assigned when sharing the specified object.

type

Query parameter

String. Type of the object. Valid values are:

QUESTION_ANSWER_BOOK for answers.
PINBOARD_ANSWER_BOOK for pinboards.
LOGICAL_TABLE for any data object such as a table, worksheet, or view.
LOGICAL_COLUMN for a column of any data object such as tables, worksheets, or views.

id

Path parameter

String. The GUID of the object to query.

dependentshare Optional

Query parameter

Boolean. Object permission details for the dependent objects. When set to true, the API returns the permission details for the dependent objects for the specified GUID.

permissiontype

Query parameter

String. Valid values are:

EFFECTIVE for object permissions inherited from group privileges.
DEFINED for the explicitly defined permissions that a user may have assigned when sharing the specified object.

Example request

cURL

curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/metadata/d084c256-e284-4fc4-b80c-111cb606449a/permissions?type=PINBOARD_ANSWER_BOOK&dependentshare=false&permissiontype=EFFECTIVE'

Request URL

https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/metadata/d084c256-e284-4fc4-b80c-111cb606449a/permissions?type=PINBOARD_ANSWER_BOOK&dependentshare=false&permissiontype=EFFECTIVE'

Example response

If the GET operation is successful, the API returns a response with the permission details for the specified object.

Note that the shareMode property indicates the object-level permission assigned to a given user.
- READ_ONLY indicates view permissions to an object
- MODIFY indicates edit permissions to an object
If the user doesn’t have access to the specified object, the API returns a 403 unauthorized error.

{
  "d084c256-e284-4fc4-b80c-111cb606449a": {
    "permissions": {
      "59481331-ee53-42be-a548-bd87be6ddd4a": {
        "topLevelObjectId": "d084c256-e284-4fc4-b80c-111cb606449a",
        "shareMode": "READ_ONLY",
        "dependents": [
          {
            "id": "d0f39bd0-47ae-45af-a214-bea2286e220a",
            "name": "Total Quantity Purchased by Product",
            "author": "d084c256-e284-4fc4-b80c-111cb606449a",
            "type": "QUESTION_ANSWER_BOOK",
            "shareMode": "READ_ONLY",
            "isHidden": true,
            "owner": "d084c256-e284-4fc4-b80c-111cb606449a"
          },
          {
            "id": "a9466299-4e89-4a2f-a1b2-d87337a4afc6",
            "name": "Total Sales by Store",
            "author": "d084c256-e284-4fc4-b80c-111cb606449a",
            "type": "QUESTION_ANSWER_BOOK",
            "shareMode": "READ_ONLY",
            "isHidden": true,
            "owner": "d084c256-e284-4fc4-b80c-111cb606449a"
          },
          {
            "id": "d766e0da-2fa6-4af5-ab44-d86f28326c3a",
            "name": "Total Sales by Product Type",
            "author": "d084c256-e284-4fc4-b80c-111cb606449a",
            "type": "QUESTION_ANSWER_BOOK",
            "shareMode": "READ_ONLY",
            "isHidden": true,
            "owner": "d084c256-e284-4fc4-b80c-111cb606449a"
          }
        ]
      }
    }
  }
}

Response codes

HTTP status code	Description
200	Successful operation
400	Invalid parameter value

HTTP status code

Description

200

Successful operation

400

Invalid parameter value

Get object permission details for multiple object types

To query object permission details for multiple object types and IDs in bulk, send a POST request to the /tspublic/v1/security/effectivepermissionbulk endpoint.

Resource URL

POST /tspublic/v1/security/effectivepermissionbulk

Request parameters

Form parameter Description

Form parameter	Description
`idsbytype`	Array of Strings. A JSON array of the object IDs for each object type. Valid object types are: `QUESTION_ANSWER_BOOK` for answers. `PINBOARD_ANSWER_BOOK` for pinboards. `LOGICAL_TABLE` for any data object such as a table, worksheet, or view. `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. For example, to get permission details for specific pinboards and answers, specify the value of `idsbytype` as shown here: {"PINBOARD_ANSWER_BOOK": ["d084c256-e284-4fc4-b80c-111cb606449a"], "QUESTION_ANSWER_BOOK": ["92f48c07-9c62-4bfa-81ac-55f3049165b4"]}
`dependentshare` Optional	Boolean. Object permission details for the dependent objects. When set to `true`, the API returns the permission details for the dependent objects for the specified object types and IDs.

idsbytype

Array of Strings. A JSON array of the object IDs for each object type. Valid object types are:

QUESTION_ANSWER_BOOK for answers.
PINBOARD_ANSWER_BOOK for pinboards.
LOGICAL_TABLE for any data object such as a table, worksheet, or view.
LOGICAL_COLUMN for a column of any data object such as tables, worksheets, or views.

For example, to get permission details for specific pinboards and answers, specify the value of idsbytype as shown here:

{"PINBOARD_ANSWER_BOOK": ["d084c256-e284-4fc4-b80c-111cb606449a"], 	"QUESTION_ANSWER_BOOK": ["92f48c07-9c62-4bfa-81ac-55f3049165b4"]}

dependentshare Optional

Boolean. Object permission details for the dependent objects. When set to true, the API returns the permission details for the dependent objects for the specified object types and IDs.

Example request

cURL

curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'idsbytype=%7B%20%09%22PINBOARD_ANSWER_BOOK%22%3A%20%5B%22d084c256-e284-4fc4-b80c-111cb606449a%22%5D%2C%20%09%22QUESTION_ANSWER_BOOK%22%3A%20%5B%2292f48c07-9c62-4bfa-81ac-55f3049165b4%22%5D%20%7D&dependentshare=true' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/effectivepermissionbulk'

Request URL

https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/effectivepermissionbulk

Example response

If the data query operation is successful, the API returns the object permission details for the specified object IDs and types.

Note that the shareMode property indicates the object-level permission assigned to a given user.
- READ_ONLY indicates view permissions to an object
- MODIFY indicates edit permissions to an object
If the user doesn’t have access to the specified objects, the API returns a 403 unauthorized error.
If the user doesn’t have access to one of the specified objects, the API returns only those objects to which a user has READ_ONLY or MODIFY permissions.

{
  "QUESTION_ANSWER_BOOK": {
    "92f48c07-9c62-4bfa-81ac-55f3049165b4": {
      "permissions": {
        "59481331-ee53-42be-a548-bd87be6ddd4a": {
          "topLevelObjectId": "92f48c07-9c62-4bfa-81ac-55f3049165b4",
          "shareMode": "READ_ONLY",
          "dependents": [
            {
              "id": "44cb25f9-9032-4d45-9d74-bbf66e1502f0",
              "name": "Username",
              "author": "965b5f46-7162-4c16-8aac-7ab26f313b25",
              "type": "LOGICAL_COLUMN",
              "shareMode": "READ_ONLY",
              "isHidden": false,
              "owner": "965b5f46-7162-4c16-8aac-7ab26f313b25",
              "ownerName": "Credit Usage Worksheet"
            },
            {
              "id": "5ff6043f-a340-46e0-98f1-84b4b3a96f1b",
              "name": "Credit Window ID",
              "author": "965b5f46-7162-4c16-8aac-7ab26f313b25",
              "type": "LOGICAL_COLUMN",
              "shareMode": "READ_ONLY",
              "isHidden": false,
              "owner": "965b5f46-7162-4c16-8aac-7ab26f313b25",
              "ownerName": "Credit Usage Worksheet"
            }
          ],
          "answerBookQueryEditable": true
        }
      }
    }
  },
  "PINBOARD_ANSWER_BOOK": {
    "d084c256-e284-4fc4-b80c-111cb606449a": {
      "permissions": {
        "59481331-ee53-42be-a548-bd87be6ddd4a": {
          "topLevelObjectId": "d084c256-e284-4fc4-b80c-111cb606449a",
          "shareMode": "READ_ONLY",
          "dependents": [
            {
              "id": "d0f39bd0-47ae-45af-a214-bea2286e220a",
              "name": "Total Quantity Purchased by Product",
              "author": "d084c256-e284-4fc4-b80c-111cb606449a",
              "type": "QUESTION_ANSWER_BOOK",
              "shareMode": "READ_ONLY",
              "isHidden": true,
              "owner": "d084c256-e284-4fc4-b80c-111cb606449a"
            },
            {
              "id": "d766e0da-2fa6-4af5-ab44-d86f28326c3a",
              "name": "Total Sales by Product Type",
              "author": "d084c256-e284-4fc4-b80c-111cb606449a",
              "type": "QUESTION_ANSWER_BOOK",
              "shareMode": "READ_ONLY",
              "isHidden": true,
              "owner": "d084c256-e284-4fc4-b80c-111cb606449a"
            }
          ]
        }
      }
    }
  }
}

Response codes

HTTP status code	Description
200	Successful operation
400	Invalid parameter value

HTTP status code

Description

200

Successful operation

400

Invalid parameter value

Was this page helpful?Give us feedback!

ThoughtSpot is the Modern Analytics Cloud company. Our Live Analytics services deliver personalized, actionable insights at the point of impact for every user, at every level.

Product

By Role

By Department

Solutions

About Us

Connect

(800) 508-7008

Security APIs

Supported operations

Share objects with another user

Resource URL

Request parameters

Example request

Example response

Response codes

Share a visualization with another user or user group

Resource URL

Request parameters

Example request

Example response

Response codes

Get object permission details for a specific object type

Resource URL

Request parameters

Example request

Example response

Response codes

Get permission details for a specific object ID

Resource URL

Request parameters

Example request

Example response

Response codes

Get object permission details for multiple object types

Resource URL

Request parameters

Example request

Example response

Response codes

Product

By Role

By Department

Solutions

About Us

Connect