openapi: 3.0.0
info:
title: ThoughtSpot Public REST 10.1.0.cl Users API
version: '2.0'
servers:
- url: '{base-url}'
variables:
base-url:
default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: Users
paths:
/api/rest/2.0/users/activate:
post:
operationId: activateUser
description: "\n <span class=\"since-beta-tag\">Version: 9.7.0.cl or later</span>\n\nActivates a deactivated user account.\n\nRequires `ADMINISTRATION` (**Can administer Thoughtspot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\nTo activate an inactive user account, the API request body must include the following information:\n\n- Username or the GUID of the user account.\n- Auth token generated for the deactivated user. The auth token is sent in the API response when a user is deactivated.\n- Password for the user account.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActivateUserRequest'
required: true
parameters: []
responses:
'200':
description: User activated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/change-password:
post:
operationId: changeUserPassword
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nUpdates the current password of the user.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeUserPasswordRequest'
required: true
parameters: []
responses:
'204':
description: User password change operation successful.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/create:
post:
operationId: createUser
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nCreates a user in ThoughtSpot.\n\nThe API endpoint allows you to configure several user properties such as email address, account status, share notification preferences, and sharing visibility. You can provision the user to [groups](https://docs.thoughtspot.com/cloud/latest/groups-privileges) and [Orgs](https://docs.thoughtspot.com/cloud/latest/orgs-overview). You can also add Liveboard, Answer, and Worksheet objects to the user’s favorites list, assign a default Liveboard for the user, and set user preferences.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
required: true
parameters: []
responses:
'200':
description: User successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/deactivate:
post:
operationId: deactivateUser
description: "\n <span class=\"since-beta-tag\">Version: 9.7.0.cl or later</span>\n\nDeactivates a user account.\n\nRequires `ADMINISTRATION` (**Can administer Thoughtspot**) privilege. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\nTo deactivate a user account, the API request body must include the following information:\n\n- Username or the GUID of the user account\n- Base URL of the ThoughtSpot instance\n\nIf the API request is successful, ThoughtSpot returns the activation URL in the response. The activation URL is valid for 14 days and can be used to re-activate the account and reset the password of the deactivated account.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeactivateUserRequest'
required: true
parameters: []
responses:
'200':
description: User deactivated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseActivationURL'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/{user_identifier}/delete:
post:
operationId: deleteUser
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nDeletes a user from the ThoughtSpot system.\n\nIf you want to remove a user from a specific Org but not from ThoughtSpot, update the group and Org mapping properties of the user object via a POST API call to the [/api/rest/2.0/users/{user_identifier}/update](#/http/api-endpoints/users/update-user) endpoint.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
parameters:
- in: path
name: user_identifier
required: true
schema:
type: string
description: GUID / name of the user
responses:
'204':
description: User successfully deleted.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/force-logout:
post:
operationId: forceLogoutUsers
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nEnforces logout on current user sessions. \n\nUse this API with caution as it may invalidate active user sessions and force users to re-login. Make sure you specify the usernames or GUIDs. If you pass null values in the API call, all user sessions on your cluster become invalid, and the users are forced to re-login.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ForceLogoutUsersRequest'
required: true
parameters: []
responses:
'204':
description: Force logging out of users operation successful.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/import:
post:
operationId: importUsers
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nImports user data from external databases into ThoughtSpot. During the user import operation:\n\n* If the specified users are not available in ThoughtSpot, the users are created and assigned a default password. Defining a `default_password` in the API request is optional.\n* If `delete_unspecified_users` is set to `true`, the users not specified in the API request, excluding the `tsadmin`, `guest`, `system` and `su` users, are deleted.\n* If the specified user objects are already available in ThoughtSpot, the object properties are updated and synchronized as per the input data in the API request.\n\nA successful API call returns the object that represents the changes made in the ThoughtSpot system.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportUsersRequest'
required: true
parameters: []
responses:
'200':
description: Import users operation successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ImportUsersResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/reset-password:
post:
operationId: resetUserPassword
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nResets the password of a user account. Administrators can reset password on behalf of a user.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResetUserPasswordRequest'
required: true
parameters: []
responses:
'204':
description: User password reset operation successful.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/search:
post:
operationId: searchUsers
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nGets a list of users available on the ThoughtSpot system.\n\nTo get details of a specific user, specify the user GUID or name. You can also filter the API response based on groups, Org ID, user visibility, account status, user type, and user preference settings and favorites.\n\nAvailable to all users. Users with `ADMINISTRATION` (**Can administer ThoughtSpot**) privileges can view all users properties. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n**NOTE**: If the API returns an empty list, consider increasing the value of the `record_size` parameter. To search across all available users, set `record_size` to `-1`.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchUsersRequest'
required: true
parameters: []
responses:
'200':
description: User search result.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/users/{user_identifier}/update:
post:
operationId: updateUser
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nUpdates the properties of a user object.\n\nYou can modify user properties such as username, email, and share notification settings. You can also assign new groups and Orgs, remove the user from a group or Org, reset password, and modify user preferences.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `USER_ADMINISTRATION` (**Can manage users**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
required: true
parameters:
- in: path
name: user_identifier
required: true
schema:
type: string
description: GUID / name of the user
responses:
'204':
description: User successfully updated.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ResponseActivationURL:
type: object
properties:
activation_link:
type: string
description: Activation link to activate the user.
nullable: true
description: The object representation with activation link.
DeactivateUserRequest:
type: object
properties:
user_identifier:
description: Unique ID or name of the user.
type: string
base_url:
description: Base url of the cluster.
type: string
required:
- user_identifier
- base_url
UpdateUserRequest:
type: object
properties:
name:
description: Name of the user. The username string must be unique.
type: string
display_name:
description: A unique display name string for the user account, usually their first and last name
type: string
visibility:
description: Visibility of the users. When set to SHARABLE, the user is visible to other users and groups when they try to share an object.
type: string
enum:
- SHARABLE
- NON_SHARABLE
email:
description: Email of the user account
type: string
account_status:
description: Current status of the user account. The `SUSPENDED` user state indicates a transitional state applicable to IAMv2 users only.
type: string
enum:
- ACTIVE
- INACTIVE
- EXPIRED
- LOCKED
- PENDING
- SUSPENDED
notify_on_share:
description: 'User preference for receiving email notifications when another ThoughtSpot user
shares a metadata object such as Answer, Liveboard, or Worksheet.'
type: boolean
nullable: true
show_onboarding_experience:
description: The user preference for revisiting the onboarding experience.
type: boolean
nullable: true
onboarding_experience_completed:
description: Indicates if the user has completed the onboarding and allows turning off the onboarding walkthrough.
type: boolean
nullable: true
account_type:
description: Type of the account.
type: string
enum:
- LOCAL_USER
- LDAP_USER
- SAML_USER
- OIDC_USER
- REMOTE_USER
group_identifiers:
description: GUIDs or names of the groups.
type: array
items:
type: string
home_liveboard_identifier:
description: 'GUID of the Liveboard to set a default Liveboard for the user. ThoughtSpot displays
this Liveboard on the Home page when the user logs in.'
type: string
favorite_metadata:
description: Metadata objects to add to the user's favorites list.
type: array
items:
$ref: '#/components/schemas/FavoriteMetadataInput'
org_identifiers:
description: IDs of the Orgs.
type: array
items:
type: string
operation:
description: Type of update operation. Default operation type is REPLACE
default: REPLACE
type: string
enum:
- ADD
- REMOVE
- REPLACE
preferred_locale:
description: 'Locale for the user. When setting this value, do not set use_browser_language
to true, otherwise the browser''s language setting will take precedence and the
preferred_locale value will be ignored.'
type: string
enum:
- en-CA
- en-GB
- en-US
- de-DE
- ja-JP
- zh-CN
- pt-BR
- fr-FR
- fr-CA
- es-US
- da-DK
- es-ES
- fi-FI
- sv-SE
- nb-NO
- pt-PT
- nl-NL
- it-IT
- ru-RU
- en-IN
- de-CH
- en-NZ
- es-MX
- en-AU
- zh-Hant
- ko-KR
- en-DE
use_browser_language:
description: 'Flag to indicate whether to use the browser locale for the user in the UI.
When set to true, the preferred_locale value is unset and the browser''s
language setting takes precedence. <br/> <span class="since-beta-tag">Version: 26.3.0.cl or later</span>'
type: boolean
nullable: true
extended_properties:
description: Properties for the user
type: object
extended_preferences:
description: Preferences for the user
type: object
Object_ID_And_Name:
type: object
properties:
id:
type: string
description: The unique identifier of the object.
nullable: true
name:
type: string
description: Name of the object.
nullable: true
description: The object representation with ID and Name.
ErrorResponse:
type: object
properties:
error:
type: object
nullable: true
ResetUserPasswordRequest:
type: object
properties:
new_password:
description: New password for the user.
type: string
user_identifier:
description: GUID or name of the user.
type: string
required:
- new_password
- user_identifier
CreateUserRequest:
type: object
properties:
name:
description: Name of the user. The username string must be unique.
type: string
display_name:
description: A unique display name string for the user account, usually their first and last name
type: string
password:
description: Password for the user account. For IAMv2 users, you must set this password if you do not want to trigger an activation email.
type: string
email:
description: Email of the user account
type: string
account_type:
description: Type of the account.
default: LOCAL_USER
type: string
enum:
- LOCAL_USER
- LDAP_USER
- SAML_USER
- OIDC_USER
- REMOTE_USER
account_status:
description: Current status of the user account. The `SUSPENDED` user state indicates a transitional state applicable to IAMv2 users only.
default: ACTIVE
type: string
enum:
- ACTIVE
- INACTIVE
- EXPIRED
- LOCKED
- PENDING
- SUSPENDED
org_identifiers:
description: List of Org IDs to which the user belongs.
type: array
items:
type: string
group_identifiers:
description: GUIDs or names of the groups to which the newly created user belongs.
type: array
items:
type: string
visibility:
description: Visibility of the users. When set to SHARABLE, the user is visible to other users and groups when they try to share an object.
default: SHARABLE
type: string
enum:
- SHARABLE
- NON_SHARABLE
notify_on_share:
description: 'User preference for receiving email notifications when another ThoughtSpot
user shares a metadata object such as Answer, Liveboard, or Worksheet.'
default: true
type: boolean
nullable: true
show_onboarding_experience:
description: The user preference for revisiting the onboarding experience.
default: true
type: boolean
nullable: true
onboarding_experience_completed:
description: flag to get the on-boarding experience is completed or not.
default: false
type: boolean
nullable: true
home_liveboard_identifier:
description: 'GUID of the Liveboard to set a default Liveboard for the user.
ThoughtSpot displays this Liveboard on the Home page when the user logs in.'
type: string
favorite_metadata:
description: Metadata objects to add to the user's favorites list.
type: array
items:
$ref: '#/components/schemas/FavoriteMetadataInput'
preferred_locale:
description: 'Locale for the user. When setting this value, do not set use_browser_language
to true, otherwise the browser''s language setting will take precedence and the
preferred_locale value will be ignored.'
type: string
enum:
- en-CA
- en-GB
- en-US
- de-DE
- ja-JP
- zh-CN
- pt-BR
- fr-FR
- fr-CA
- es-US
- da-DK
- es-ES
- fi-FI
- sv-SE
- nb-NO
- pt-PT
- nl-NL
- it-IT
- ru-RU
- en-IN
- de-CH
- en-NZ
- es-MX
- en-AU
- zh-Hant
- ko-KR
- en-DE
use_browser_language:
description: 'Flag to indicate whether to use the browser locale for the user in the UI.
When set to true, the preferred_locale value is unset and the browser''s
language setting takes precedence. <br/> <span class="since-beta-tag">Version: 26.3.0.cl or later</span>'
type: boolean
nullable: true
extended_properties:
description: Properties for the user
type: object
extended_preferences:
description: Preferences for the user
type: object
trigger_welcome_email:
description: Flag to indicate whether welcome email should be sent to user. This parameter is applied only on clusters on which IAM is disabled.
type: boolean
nullable: true
trigger_activation_email:
description: "Flag to indicate whether activation email should be sent to the user. Default value for IAMv2 users is set to true. Users must either set this to false, or enter a valid \npassword if they do not want to trigger an activation email."
type: boolean
nullable: true
required:
- name
- display_name
- email
ImportUserType:
type: object
required:
- name
properties:
id:
type: string
description: Unique identifier of the user.
nullable: true
name:
type: string
description: Name of the user.
ImportUser:
type: object
required:
- user_identifier
- display_name
properties:
user_identifier:
type: string
description: Unique ID or name of the user.
display_name:
type: string
description: Display name of the user.
password:
type: string
description: Password of the user.
nullable: true
account_type:
type: string
enum:
- LOCAL_USER
- LDAP_USER
- SAML_USER
- OIDC_USER
- REMOTE_USER
description: Type of the user account.
nullable: true
account_status:
type: string
enum:
- ACTIVE
- INACTIVE
- EXPIRED
- LOCKED
- PENDING
- SUSPENDED
description: Status of the user account.
nullable: true
email:
type: string
description: Email address of the user.
nullable: true
org_identifiers:
type: array
items:
type: string
description: ID or name of the Orgs to which the user belongs.
nullable: true
group_identifiers:
type: array
items:
type: string
description: ID or name of the groups to which the user belongs.
nullable: true
visibility:
type: string
enum:
- SHARABLE
- NON_SHARABLE
description: Visibility of the users. The SHARABLE property makes a user visible to other users and group, who can share objects with the user.
nullable: true
notify_on_share:
type: boolean
default: true
description: Notify user when other users or groups share metadata objects
nullable: true
show_onboarding_experience:
type: boolean
description: Show or hide the new user onboarding walkthroughs
nullable: true
onboarding_experience_completed:
type: boolean
description: Revisit the new user onboarding walkthroughs
nullable: true
home_liveboard_identifier:
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thoughtspot/refs/heads/main/openapi/thoughtspot-users-api-openapi.yml