User API

The User APIs enable you to manage user- and group-related operations in the ThoughtSpot system.

You can use the User APIs to manage your users and groups in ThoughtSpot. For example, you may want to view all users and groups in your ThoughtSpot cluster.

Transfer ownership

Use this API to transfer ownership of all objects from one user to another.

You cannot transfer objects to or from the system user or the administrative user.

Resource URL

post /tspublic/v1/user/transfer/ownership

Request Parameters

fromUserName

Username to transfer from.

Data type

string

toUserName

Username to transfer to.

Data type

string

Request Examples

  • cURL

    curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Requested-By: ThoughtSpot' 'https://<instance>/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1'
  • Request URL

    https://<instance>/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1

Response Example

Not applicable
204 - Successful login

Synchronize principals

Use this API to synchronize ThoughtSpot users and groups with your external database. The payload takes principals containing all users and groups present in the external database and a successful API call returns the object that represents the changes that were made in ThoughtSpot system. This means the following:

  • Objects (users or groups) present in ThoughtSpot, but not present in the external list - will be deleted in ThoughtSpot.

  • Objects present in ThoughtSpot, and present in the external list - will be updated such that the object attributes in ThoughtSpot match those present in the list. This includes group membership.

  • Objects not present in ThoughtSpot, and present in the external list - will be created in ThoughtSpot.

Resource URL

`post` /tspublic/v1/user/sync

Request Parameters

This API uses multipart/form-data content type.

principals

Specifies a list of principal objects.

This is ideally a JSON file containing containing all users and groups present in the external database. Data type;; string

applyChanges

A flag indicating whether to sync the users and groups to the system, and apply the difference evaluated.

Use this parameter to validate a difference before applying changes. Data type;; boolean

removeDeleted

A flag indicating whether to remove deleted users/groups.

When true, this flag removes any deleted users or groups. Data type;; boolean

password

Specifies a password.

Data type

string

Request Example

  • cURL

    curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' -d 'applyChanges=false' 'https://<instance>/callosum/v1/tspublic/v1/user/sync'
  • Request URL

    https://<instance>/callosum/v1/tspublic/v1/user/sync

Response Example

This example covers user objects (with emails), group objects, and their relationships.

  • created and modified dates may be left blank for new users.

  • principalTypeEnum value specifies if the principal is a user or a group.

Here, test1 user belongs to two groups - Customer Success and Marketing. test2 belongs to the group Administrator. All is a default group to which every user belongs; you may omit it from the input.

Set visibility to NON_SHARABLE if you do not want users to be able to share objects with users in this group.

[
  { "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" }
]

Change password

Use this API to change the password of a user.

Resource URL

`post` /tspublic/v1/user/updatepassword

Request Parameters

name

Name of the user.

Data type

string

currentpassword

The current password of the user.

Data type

string

password

A new password of the user.

Data type

string

Request Example

  • cURL

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' --header 'X-Requested-By: ThoughtSpot' -d 'name=guest&currentpassword=test&password=foobarfoobar' 'https://<instance>/callosum/v1/tspublic/v1/user/updatepassword'
  • Request URL

https://<instance>/callosum/v1/tspublic/v1/user/updatepassword

Response Example

Not applicable
204 - Successful password update

Fetch users and groups

Use this API to get a list of all users, groups, and their inter-dependencies in the form of principal objects.

A typical principal object contains the following properties:

name

Name of the principal. This field, in conjunction with the object that is either a user or a group, must be unique, separately for users and for groups. You can have both a user xyz and a group xyz.

displayName

Display name of the principal.

description

Description of the principal.

mail

Email address of the user. This field is for user principals only. The system ignores it for groups.

principalTypeEnum

Type of the user created in the ThoughtSpot system.

  • LOCAL_USER is a user who is validated through a password saved in the ThoughtSpot database)

  • LOCAL_GROUP is a group saved in the ThoughtSpot database

password

Password of the user. This field is only valid for user principals only. The system ignores it for group principals.

The password is necessary in following circumstances:

  • if the user is a LOCAL_USER

  • at the time the user is created in the system

groupNames

Group names to which the principal belongs. Both users and groups can belong to other groups.

Resource URL

`get /tspublic/v1/user/list

Request Example

  • cURL

    curl -X GET --header 'Accept: application/json' 'https://<instance>/callosum/v1/tspublic/v1/user/list'
  • Request URL

    https://<instance>/callosum/v1/tspublic/v1/user/list

Response Example

[
  {
    "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 direclty to rls-group-5",
    "created": 1459376495060,
    "modified": 1459376590681,
    "principalTypeEnum": "LOCAL_GROUP",
    "groupNames": rls-group-5,
    "visibility": "DEFAULT"
  }
  ]