# REST API v1 - Security API endpoints > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/security-api-v1 # REST API v1 - Security API endpoints > **IMPORTANT:** The REST API v1 endpoints are deprecated and replaced with the REST API v2 endpoints. Your existing integrations with REST API v1 endpoints will continue to function without disruption until further notice. ThoughtSpot strongly recommends migrating your integrations to the REST API v2 endpoints. ## Supported operations The Security APIs allow you to share ThoughtSpot objects, such as Liveboards and visualizations, with other users or user groups in ThoughtSpot. | API endpoint | Available from | | --- | --- | | `[**POST** /tspublic/v1/security/share]({{navprefix}}/{{security-api}}#share-object)` Shares ThoughtSpot objects with another user or user group. | ThoughtSpot Cloud ts7.jun.cl ThoughtSpot Software 7.1.1 | | `[**POST** /tspublic/v1/security/shareviz]({{navprefix}}/{{security-api}}#shareviz)` Shares a specific visualization with another user or user group. | ThoughtSpot Cloud ts7.jun.cl ThoughtSpot Software 7.1.1 | | `[**GET** /tspublic/v1/security/metadata/permissions]({{navprefix}}/{{security-api}}#obj-permission-all)` Gets object permission details for a specific object type. | ThoughtSpot Cloud ts7.sep.cl ThoughtSpot Software 7.2.1 | | `[**GET** /tspublic/v1/security/metadata/{id}/permissions]({{navprefix}}/{{security-api}}#obj-permission-id)` Gets object permission details for a specific object ID. | ThoughtSpot Cloud ts7.sep.cl ThoughtSpot Software 7.2.1 | | `[**GET** /tspublic/v1/security/effectivepermissionbulk]({{navprefix}}/{{security-api}}#get-obj-perm-bulk)` Gets object permission details for multiple object types and IDs. | ThoughtSpot Cloud ts7.sep.cl ThoughtSpot Software 7.2.1 | ### Required permissions - To query object permissions, you must have administrator access. - To share an object or visualization with another user, you must have edit access to the object. ## Share objects with another user To programmatically share ThoughtSpot objects with another user or user group, use the `/tspublic/v1/security/share` API. When you share an object like a Liveboard 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 answers. - `PINBOARD_ANSWER_BOOK` to share Liveboards. - `LOGICAL_TABLE` to share a data object such as a Table, Model, or View. - `LOGICAL_COLUMN` to share a column of any data object such as Tables, Models, or Views. | | `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":{"":{"shareMode":""}}}`. - 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 shown here: ```JSON {"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: ```JSON {"permissions": {"e7040a64-7ff1-4ab9-a1b0-f1acac596866": {"shareMode": "READ_ONLY"}, "f7b8f511-317c-485d-8131-26cf084ef47b": {"shareMode": "READ_ONLY"}}} ``` Similarly, to share objects with one or several user groups, specify the GUIDs and access permission type in the following format: ```JSON {"permissions":{"59481331-ee53-42be-a548-bd87be6ddd4a":{"shareMode":"READ_ONLY"}}} ``` ```JSON {"permissions": {"0f7af46f-e48c-4cca-b60f-d63d5ddbe59f": {"shareMode": "MODIFY"}, "e5fc80ce-db65-4921-8ece-c7bb44fceca1": {"shareMode": "READ_ONLY"}}} ``` > **IMPORTANT:** 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` | _Array of Strings_. Email addresses to notify when the object is shared. | | `notify` _Optional_ | _Boolean_. If set to `true`, an object share notification is sent to the specified email addresses. | | `message` _Optional_ | _String_. The message text to send in the object share notification email. | | `useCustomEmbedUrls` | _Boolean_. When set to `true`, ThoughtSpot sends a customized link with the host application URL in the object share notification. You can use this attribute to generate links for embedded ThoughtSpot objects. | ### Example request cURL ```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"]¬ify=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 Liveboard with another user or user group, use the `/tspublic/v1/security/shareviz` API. > **IMPORTANT:** Sharing a visualization implicitly shares the entire Liveboard with the recipient. If email notifications for object sharing are enabled, a notification with a link to the shared visualization will be sent to the recipient’s email address. Although this link opens the shared visualization, recipients can also access other visualizations in the Liveboard. The /tspublic/v1/security/shareviz API endpoint provides only read-only access to the shared visualization. ### 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 Liveboard to which the visualization belongs. | | `principalids` | _String_. The GUID of the users and groups to which you want to share the visualization. | | `vizid` | _String_. The GUID of visualization. | | `emailshares` | _Sring_. Email addresses to notify when the object is shared. | | `notify` _Optional_ | _Boolean_. If set to `true`, an object share notification is sent to the specified email addresses. | | `message` _Optional_ | _String_. The message text to send in the notification email. | | `useCustomEmbedUrls` | _Boolean_. When set to `true`, ThoughtSpot sends a customized link with the host application URL in the object share notification. You can use this attribute to generate links for embedded ThoughtSpot objects. | ### Example request cURL ```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=%5B%2259481331-ee53-42be-a548-bd87be6ddd4a%22%5D&vizid=e9753523-5de5-41ef-8d8c-b840f0260ea0&emailshares=%5Btsuser%40thoughtspot.com%5D¬ify=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 | ## 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 Liveboard 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 Name | Parameter Type | Description | | --- | --- | --- | | `type` | Query parameter | _String_. Type of the object. Valid values are: - `QUESTION_ANSWER_BOOK` for answers. - `PINBOARD_ANSWER_BOOK` for Liveboards. - `LOGICAL_TABLE` for any data object such as a Table, Model, or View. - `LOGICAL_COLUMN` for a column of any data object such as tables, models, 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 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. ```JSON { "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 | | **403** | Unauthorized request | ## 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/permissions` endpoint. ### Resource URL GET /tspublic/v1/security/metadata/{id}/permissions ### Request parameters | Parameter Name | Parameter Type | Description | | --- | --- | --- | | `type` | Query parameter | _String_. Type of the object. Valid values are: - `QUESTION_ANSWER_BOOK` for answers. - `PINBOARD_ANSWER_BOOK` for Liveboards. - `LOGICAL_TABLE` for any data object such as a Table, Model, or View. - `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, 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 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. ```JSON { "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 | | **403** | Unauthorized request | ## Get object permission details for multiple object types To query object permission details for multiple object types and IDs, send a `POST` request to the `/tspublic/v1/security/effectivepermissionbulk` endpoint. ### Resource URL POST /tspublic/v1/security/effectivepermissionbulk ### Request parameters | 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 Liveboards. - `LOGICAL_TABLE` for any data object such as a Table, Model, or View. - `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, or Views. For example, to get permission details for specific Liveboards 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 of the specified object types and IDs. | ### Example request cURL ```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. ```JSON { "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 | | **403** | Unauthorized request |