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
|
|
|
|
|
Share objects with another user
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.
Request parameters
Form parameter | Description | ||
---|---|---|---|
|
String. Type of metadata object. Specify one of the following values as a metadata object type:
|
||
|
String. A JSON array of the GUIDs of the objects to be shared. |
||
|
String. A string with the GUIDs of the user or user group, and the type of access privilege.
For example, to provide read-only access to a user with a GUID of The following example shows how to set the permission string to provide read-only access to multiple users:
|
||
|
String. The email address of the user accounts with whom you want to share the objects. |
||
|
Boolean. When set to |
||
|
String. The message text to send in the notification email. |
||
|
Boolean. When set to |
Example request
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"]¬ify=false&useCustomEmbedUrls=true' \
'https://<ThoughtSpot-host/callosum/v1/tspublic/v1/security/share'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/share
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.
Request parameters
Form parameter | Description |
---|---|
|
String. Type of the metadata object. The valid value is |
|
String. The GUID of the pinboard to which the visualization belongs. |
|
String. A JSON array of the GUID of the users with whom you want to share the visualization. |
|
String. The GUID of visualization. |
|
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 |
|
Boolean. When set to |
|
String. The message text to send in the notification email. |
|
Boolean. When set to |
Example request
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]¬ify=true&useCustomEmbedUrls=false' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/shareviz'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/security/shareviz
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.
Request parameters
Parameter | Type | Description |
---|---|---|
|
Query parameter |
String. Type of the object. Valid values are:
|
|
Query parameter |
String. A JSON array of the GUIDs of the objects. |
|
Query parameter |
Boolean. Object permission details for the dependent objects. When set to |
|
Query parameter |
String. Valid values are:
|
Example request
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'
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
orMODIFY
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"
}
]
}
}
}
}
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.
Request parameters
Parameter | Type | Description |
---|---|---|
|
Query parameter |
String. Type of the object. Valid values are:
|
|
Path parameter |
String. The GUID of the object to query. |
|
Query parameter |
Boolean. Object permission details for the dependent objects. When set to |
|
Query parameter |
String. Valid values are:
|
Example request
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'
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"
}
]
}
}
}
}
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.
Request parameters
Form parameter | Description |
---|---|
|
Array of Strings. A JSON array of the object IDs for each object type. Valid object types are:
For example, to get permission details for specific pinboards and answers, specify the value of {"PINBOARD_ANSWER_BOOK": ["d084c256-e284-4fc4-b80c-111cb606449a"], "QUESTION_ANSWER_BOOK": ["92f48c07-9c62-4bfa-81ac-55f3049165b4"]} |
|
Boolean. Object permission details for the dependent objects. When set to |
Example request
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'
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
orMODIFY
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"
}
]
}
}
}
}
}