User APIs
The User API endpoints allow you to programmatically manage ThoughtSpot users.
Supported operations
|
|
|
|
|
|
|
|
|
Create a user
To programmatically create a user account in the ThoughtSpot system, send a POST
request to /tspublic/v1/user/
API endpoint.
|
Request parameters
Form parameter | Description |
---|---|
|
String. Name of the user. The username string must be unique. |
|
String.Password for the user account. |
|
String. A unique display name string for the user, usually their first and last name. |
|
String. A JSON map of user properties fetched from external systems such as LDAP. If you are using Active Directory to authenticate users, and your LDAP configuration requires users to be created manually, you can upload the user properties as a JSON file. |
|
Array of strings. A JSON array of the GUIDs of groups to which you want to assign the user. The user privileges are determined by the group to which you assign the user. For example, if you assign the user to a group that has the |
|
String. Type of user. The default value is |
|
String. GUID of the tenant for which the user is being created. |
|
String. Visibility of the user. The |
Example request
curl -X POST \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Accept: application/json' \ --header 'X-Requested-By: ThoughtSpot' \ -d 'name=TS%20User&password=testy1%4022&displayname=TS%20User&usertype=LOCAL_USER&visibility=DEFAULT' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/
Example response
If the user is successfully created in ThoughtSpot, the API returns the user GUID along with the following JSON response:
{ "userContent": { "userPreferences": { "notifyOnShare": true, "showWalkMe": true, "analystOnboardingComplete": false }, "userProperties": {}, "userActivityProto": { "first_login": -1, "welcome_email_sent": false } }, "state": "ACTIVE", "assignedGroups": [ "b25ee394-9d13-49e3-9385-cd97f5b253b4" ], "inheritedGroups": [ "b25ee394-9d13-49e3-9385-cd97f5b253b4" ], "privileges": [], "type": "LOCAL_USER", "parenttype": "USER", "visibility": "DEFAULT", "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a", "displayName": "TS User", "header": { "id": "79c4cb2a-18cd-44a7-a077-6de65d1b468e", "indexVersion": 0, "generationNum": 0, "name": "TS User", "author": "59481331-ee53-42be-a548-bd87be6ddd4a", "created": 1624796017810, "modified": 1624796017810, "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", "owner": "79c4cb2a-18cd-44a7-a077-6de65d1b468e", "tags": [], "isExternal": false, "isDeprecated": false }, "complete": true, "incompleteDetail": [], "isSuperUser": false, "isSystemPrincipal": false }
Update user details
To modify the attributes of a ThoughtSpot user account, send a PUT
request to the /tspublic/v1/user/{userid}
endpoint.
This API allows the following modifications to a user profile:
-
User name modifications
-
Password reset
-
Group assignment
-
User visibility for sharing objects
-
User preferences such as viewing onboarding experience, subscribing to or unsubscribing from email notifications, and so on.
Request parameters
Form parameter | Description |
---|---|
|
String. GUID of the user. |
|
String. A JSON map of strings with the user profile attributes. |
|
String. Password string for the user account. Use this attribute to change the password of the user account. |
Example request
curl -X PUT \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Accept: application/json' \ --header 'X-Requested-By: ThoughtSpot' \ -d 'userid=4391d676-2dd8-4248-b6db-d973811f0122' \ -d 'content={"displayName": "Guest", "header": {"id": "4391d676-2dd8-4248-b6db-d973811f0122", "name": "guest1234", "displayName": "Guest", "owner": "4391d676-2dd8-4248-b6db-d973811f0122"}}' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/{userid}' \ -b 'JSESSIONID=0e97a2a6-7e9a-496a-b48b-2d66ec8b1e15'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/{userid}
JSON file example for updating user profile
{
"userContent":{
"userPreferences":{
"notifyOnShare":false,
"showWalkMe":true,
"analystOnboardingComplete":false
},
"userProperties":{
},
"userActivityProto":{
"first_login":-1,
"welcome_email_sent":false
}
},
"state":"ACTIVE",
"assignedGroups":[
"d0326b56-ef23-4c8a-8327-a30e99bcc72b",
"b25ee394-9d13-49e3-9385-cd97f5b253b4"
],
"inheritedGroups":[
"b25ee394-9d13-49e3-9385-cd97f5b253b4"
],
"privileges":[
],
"type":"LOCAL_USER",
"parenttype":"USER",
"visibility":"DEFAULT",
"tenantId":"982d6da9-9cd1-479e-b9a6-35aa05f9282a",
"displayName":"TS User2",
"header":{
"id":"d1f4f2c8-c5bb-4f20-a81d-1f24af0b3286",
"indexVersion":0,
"generationNum":0,
"name":"TS User2",
"author":"59481331-ee53-42be-a548-bd87be6ddd4a",
"created":1624846987754,
"modified":1624846987754,
"modifiedBy":"59481331-ee53-42be-a548-bd87be6ddd4a",
"owner":"d1f4f2c8-c5bb-4f20-a81d-1f24af0b3286",
"tags":[
],
"isExternal":false,
"isDeprecated":false
},
"complete":true,
"incompleteDetail":[
],
"isSuperUser":false,
"isSystemPrincipal":false
}
Get user details
To get the details of a specific user account or all users in the ThoughtSpot system, send a GET
request to /tspublic/v1/user/
API endpoint.
If you want to get a list of object headers associated with a user or user group, you can use the |
Request parameters
Query parameter | Description |
---|---|
|
String. The GUID of the user account to query. |
|
String. Username of the user that you want to query. |
You can use either |
Example request
curl -X GET \ --header 'Accept: application/json' \ --header 'X-Requested-By: ThoughtSpot' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/?userid=b995e481-d0a7-4820-b1e8-54051ede77a2'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/?userid=b995e481-d0a7-4820-b1e8-54051ede77a2
Example response
{
"userContent": {
"userPreferences": {
"notifyOnShare": true,
"showWalkMe": true,
"analystOnboardingComplete": false
},
"userProperties": {},
"userActivityProto": {
"first_login": -1,
"welcome_email_sent": false
}
},
"state": "ACTIVE",
"assignedGroups": [
"b25ee394-9d13-49e3-9385-cd97f5b253b4"
],
"inheritedGroups": [
"b25ee394-9d13-49e3-9385-cd97f5b253b4"
],
"privileges": [
"AUTHORING"
],
"type": "LOCAL_USER",
"parenttype": "USER",
"visibility": "DEFAULT",
"tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
"displayName": "kailash",
"header": {
"id": "b995e481-d0a7-4820-b1e8-54051ede77a2",
"indexVersion": 2602,
"generationNum": 2602,
"name": "kailash",
"displayName": "kailash",
"author": "59481331-ee53-42be-a548-bd87be6ddd4a",
"created": 1623728042624,
"modified": 1623728042624,
"modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
"owner": "b995e481-d0a7-4820-b1e8-54051ede77a2",
"isDeleted": false,
"isHidden": false,
"tags": [],
"type": "LOCAL_USER",
"isExternal": false,
"isDeprecated": false
},
"complete": true,
"incompleteDetail": [],
"isSuperUser": false,
"isSystemPrincipal": false
}
If no |
Delete a user account
To remove a user from the ThoughtSpot system, send a DELETE
request to the /tspublic/v1/user/{userid}
API endpoint.
Example request
curl -X DELETE \ --header 'Accept: application/json' \ --header 'X-Requested-By: ThoughtSpot' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/ee74b737-da39-4667-95ad-cc06c81ab13d'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/ee74b737-da39-4667-95ad-cc06c81ab13d
Get a list of users and groups
To get a list of all users, groups, and their inter-dependencies in the form of principal objects, use the /tspublic/v1/user/list
API endpoint.
Example request
curl -X GET \
--header 'Accept: application/json' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/list'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/list
Example response
[
{
"name": "Administrator",
"displayName": "Administration Group",
"created": 1354006445722,
"modified": 1354006445987,
"principalTypeEnum": "LOCAL_GROUP",
"groupNames": [],
"visibility": "DEFAULT"
},
{
"name": "Analyst",
"displayName": "Analyst Group",
"created": 1354006445722,
"modified": 1354006445987,
"principalTypeEnum": "LOCAL_GROUP",
"groupNames": [],
"visibility": "DEFAULT"
},
{
"name": "rls-group-3",
"displayName": "rls-group-3",
"description": "Contains directly rls-group-1, rls-group-2 and belongs directly to rls-group-5",
"created": 1459376495060,
"modified": 1459376590681,
"principalTypeEnum": "LOCAL_GROUP",
"groupNames": "rls-group-5",
"visibility": "DEFAULT"
}
]
Object properties
A typical principal object contains the following properties:
-
name
Name of the principal. This field, in conjunction with whether the object is a user or group, is used to identify a user or group. The name of the principal must be unique.
-
displayName
Display name of the principal.
-
description
Description of the principal.
-
mail
The email address of the user. This field is populated only for the user objects. It is ignored if the object type is a group.
-
principalTypeEnum
Type of the user created in the ThoughtSpot system. Valid values are:
-
LOCAL_USER
for users that are created and authenticated locally in the ThoughtSpot system. -
LOCAL_GROUP
for groups that are saved in the local database of the ThoughtSpot system.
-
-
password
The password of the user. This field is populated only for the user object. It is ignored in the case of groups.
Password is only required:
-
if the user is of
LOCAL_USER
type -
when the user is created for the first time. In subsequent updates, the user password is not modified even if it changes in the source system.
-
-
groupNames
Name of the groups to which a principal belongs. For example,
Administrator
,All
, and so on. Users can belong to multiple groups. -
visibility
If the user is visible to the other ThoughtSpot users or user groups who might want to share objects.
Change password
To change the password of a ThoughtSpot user account, use the /tspublic/v1/user/updatepassword
API endpoint.
Request parameters
Form parameter | Description |
---|---|
|
String. Name of the user account. |
|
String. The password of the currently logged-in user. Note that only users with admin privileges can change the password of a user account. |
|
String. A new password for the user specified in the name attribute. |
Example request
curl -X POST \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Accept: application/json' \ --header 'X-Requested-By: ThoughtSpot' \ -d 'name=guest¤tpassword=test&password=User1234!' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepassword'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepassword
Update a user profile
To update the profile settings of a ThoughtSpot user programmatically, you can use the /tspublic/v1/user/updatepreference
API.
The /tspublic/v1/user/updatepreference
API allows you to modify the following attributes of a ThoughtSpot user profile:
-
Email address
The email address of the user.
-
Language preference
The system locale setting. The locale setting determines the language of the ThoughtSpot UI, date, number, and currency format.
-
Notification setting
User preference for receiving email notifications when another ThoughtSpot user shares answers or pinboards.
-
Settings for revisiting the onboarding experience
The user preference for revisiting the onboarding experience.
ThoughtSpot provides an interactive guided walkthrough to onboard new users. The onboarding experience leads users through a set of actions to help users get started and accomplish their tasks quickly. The users can turn off the Onboarding experience and access it again when they need assistance with the ThoughtSpot UI.
The |
Request parameters
Form parameter | Description |
---|---|
|
String. The GUID of the user. |
|
String. Username of the user. |
|
String. The JSON map of user preferences. In the JSON map, you can define the attributes to set the following preferences for a user:
|
|
String. A 64-bit encoded string for setting user preferences in a secure manner. For example, |
If your browser or OS locale is set to a ThoughtSpot supported locale, ThoughtSpot automatically defaults to that locale. If your browser locale is not supported in ThoughtSpot, ThoughtSpot sets |
Example request
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'userid=59481331-ee53-42be-a548-bd87be6ddd4a&preferences={"showWalkMe":true,"notifyOnShare":true,"analystOnboardingComplete":false,"preferredLocale":"en-IN"}' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepreference''
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepreference
This example shows the following preference settings that you can pass as a JSON string.
{
"showWalkMe":true,
"notifyOnShare":true,
"analystOnboardingComplete":false,
"preferredLocale":"en-CA"
}
-
showWalkMe
BooleanEnables or disables the guided onboarding walkthrough. When set to
true
, the user can revisit the onboarding experience. -
notifyOnShare
BooleanSets a notification preference for receiving emails when another user shares answers or pinboards.
-
analystOnboardingComplete
BooleanIndicates if the user is onboarded.
-
preferredLocale
StringSets the ThoughtSpot locale for the specified user account. For example, to allow a user to view the ThoughtSpot UI in Deutsche, you can set the
preferredLocale
parameter tode-DE
.The allowed values are:
Locale Language da-DK
Dansk
de-DE
Deutsche
en-AU
English (Australia)
en-CA
English (Canada)
en-IN
English (India)
en-GB
English (United Kingdom)
en-US
English (United States)
es-US
Español (Latinoamérica)
es-ES
Español (España)
fr-CA
Français (Canada)
fr-FR
Français (France)
it-IT
Italiano
nl-NL
Nederland
nb-NO
Norsk
pt-BR
Português (Brasil)
pt-PT
Português (Portugal)
fi-FI
Suomi
sv-SE
Svenska
zh-CN
中文(简体)
ja-JP
日本語
Transfer ownership
When a user is removed from the ThoughtSpot application, you may want to transfer objects from the deleted user account to the account. If you are an admin user, you can programmatically transfer the ownership of one or several objects from one ThoughtSpot user account to another, use the /tspublic/v1/user/transfer/ownership
API.
Request parameters
Query parameter | Description |
---|---|
|
String. Username to transfer from. |
|
String. Username to transfer to. |
|
String. A JSON array of ThoughtSpot object IDs. |
Example request
curl -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'X-Requested-By: ThoughtSpot' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1'
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1
Synchronize principals
To programmatically synchronize user accounts and user groups with ThoughtSpot, use the /tspublic/v1/user/sync
API.
The payload takes principals containing all users and groups present in the external database. A successful API call returns the object that represents the changes made in the ThoughtSpot system.
During this operation:
-
Objects (users or groups) present in ThoughtSpot, but not present in the external list are deleted in ThoughtSpot.
-
Objects present in ThoughtSpot and the external list are updated such that the object attributes in ThoughtSpot match those present in the list.
This includes group membership.
-
Objects not present in ThoughtSpot, but present in the external list are created in ThoughtSpot.
Request parameters
This API uses multipart/form-data
content-type.
Make sure you use a JSON file encoded as |
Form parameter | Description |
---|---|
|
String. Specify a list of principal objects in the JSON file format. The JSON file can contain all users and groups present in the external database. |
|
Boolean. Specify whether to sync the users and groups to the system and apply the difference evaluated.
By default, this attribute is set to |
|
Boolean. Specify whether to remove the deleted users and user groups. By default, this attribute is set to |
|
String. The password of the admin user. |
Example request
curl -X POST \
--header 'X-Requested-By : ThoughtSpot' \
--header 'Cookie : JSESSIONID=0f534ede-f096-44d0-966a-f02be91dcb68; clientId=5ea75049-cbc9-4443-b083-2d148059c235; userGUID=a0d4311a-d123-48e5-806b-8bdc35e3e835' \
--header 'Accept: application/json' \
-F 'applyChanges=false' \
-F 'removeDeleted=false' \
-F 'principals=@principals.json;type=application/json' \
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/sync
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/sync
JSON request
The principals.json
file contains the JSON request to be sent for synchronizing users. Make sure the JSON file is encoded as application/json
in the API request.
Use the example format for the JSON requests:
[
{ "name": "Customer Success",
"displayName": "Customer Success",
"description": "CS",
"created": 1568926267025,
"modified": 1568926982242,
"principalTypeEnum": "LOCAL_GROUP",
"groupNames": [],
"visibility": "DEFAULT" },
{ "name": "All",
"displayName": "All Group",
"created": 1354006445722,
"modified": 1354006445722,
"principalTypeEnum": "LOCAL_GROUP",
"groupNames": [],
"visibility": "DEFAULT" },
{ "name": "Marketing",
"displayName": "Marketing",
"description": "Marketing Group",
"created": 1587573582931,
"modified": 1587573583003,
"principalTypeEnum": "LOCAL_GROUP",
"groupNames": [],
"visibility": "DEFAULT" },
{ "name": "test1",
"displayName": "test one",
"description": "",
"created": 1587573554475,
"modified": 1587573589986,
"mail": "test1@test.com",
"principalTypeEnum": "LOCAL_USER",
"groupNames": [ "All", "Customer Success", "Marketing" ],
"visibility": "DEFAULT" },
{ "name": "test2",
"displayName": "test two",
"created": 1587573621279,
"modified": 1587573621674,
"mail": "test2@test.com",
"principalTypeEnum": "LOCAL_USER",
"groupNames": [ "Administrator", "All" ],
"visibility": "DEFAULT" }
]
The above example covers user objects (with emails), group objects, and their relationships.
|