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.

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.

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

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 provide a read-only access.

Resource URL

POST /tspublic/v1/security/shareviz

Request parameters

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

Array of strings. 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
Was this page helpful?
×