From 6fbe6caf635c3bbf2a65a0329fee8300f5dc5972 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 25 Aug 2026 10:18:02 +0530 Subject: [PATCH 1/2] user api v1 cleanup --- .../ROOT/pages/partials/user-api-list.adoc | 28 ++++- modules/ROOT/pages/user-api.adoc | 108 +++++++++++++++++- 2 files changed, 133 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/partials/user-api-list.adoc b/modules/ROOT/pages/partials/user-api-list.adoc index 4c1944cd2..55b3dcd50 100644 --- a/modules/ROOT/pages/partials/user-api-list.adoc +++ b/modules/ROOT/pages/partials/user-api-list.adoc @@ -1,69 +1,93 @@ +[IMPORTANT] +==== +All endpoints in this table belong to the deprecated REST API v1 framework. Use the REST API v2 replacement listed for each endpoint in new implementations. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2 comparison]. +==== + [div tableContainer] -- -[width="100%" cols="2,1"] +[width="100%" cols="2,1,2"] [options='header'] |===== -|API endpoint| Available from +|API endpoint| Available from| REST API v2 replacement |`xref:user-api.adoc#create-user[**POST** /tspublic/v1/user/]` + Creates a user account. |ThoughtSpot Cloud [version noBackground]#ts7.jun.cl# + ThoughtSpot Software [version noBackground]#7.1.1# +|`POST /api/rest/2.0/users/create` |`xref:user-api.adoc#activate-user[**POST** /tspublic/v1/user/activate]` + Activates a user account.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/activate` |`xref:user-api.adoc#update-user[*PUT* /tspublic/v1/user/{userid}]` + Modifies a user account.|ThoughtSpot Cloud [version noBackground]#ts7.aug.cl# + ThoughtSpot Software [version noBackground]#7.1.1# +|`POST /api/rest/2.0/users/{user_identifier}/update` |`xref:user-api.adoc#addEmail[**PUT** /tspublic/v1/user/email]` + Modifies the email address of a user.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/{user_identifier}/update` |`xref:user-api.adoc#addOrg[*POST* /tspublic/v1/user/addtoorg]` + Adds one or several users to the specified Org. |ThoughtSpot Cloud [version noBackground]#8.10.0.cl# + ThoughtSpot Software [version noBackground]#Not available# +|`POST /api/rest/2.0/users/{user_identifier}/update` |`xref:user-api.adoc#get-user-details[*GET* /tspublic/v1/user/]` + Gets details of the users in a ThoughtSpot system.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.1.1# +|`POST /api/rest/2.0/users/search` |`xref:user-api.adoc#delete-user[*DELETE* /tspublic/v1/user/{userid}]` + Deletes a user account.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.1.1# +|`POST /api/rest/2.0/users/{user_identifier}/delete` |`xref:user-api.adoc#user-list[*GET* /tspublic/v1/user/list]` + Gets all users, groups, and their inter-dependencies.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# + ThoughtSpot Software [version noBackground]#6.0.x# +|`POST /api/rest/2.0/users/search` and `POST /api/rest/2.0/groups/search` |`xref:user-api.adoc#updatepreference-api[**POST** /tspublic/v1/user/updatepreference]` + Modifies a user profile.|ThoughtSpot Cloud [version noBackground]#ts7.jun.cl# + ThoughtSpot Software [version noBackground]#7.1.1# +|`POST /api/rest/2.0/users/{user_identifier}/update` |`xref:user-api.adoc#transfer-ownership[**POST** /tspublic/v1/user/transfer/ownership]` + Transfers the ownership of objects from one user to another.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# + ThoughtSpot Software [version noBackground]#6.0.x# +|`POST /api/rest/2.0/security/metadata/assign` |`xref:user-api.adoc#change-pwd[**POST** /tspublic/v1/user/updatepassword]` + Changes the password of a user account.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# + ThoughtSpot Software [version noBackground]#6.0.x# +|`POST /api/rest/2.0/users/change-password` |`xref:user-api.adoc#resetpassword[**POST** /tspublic/v1/user/resetpassword]` + Resets the password of a user account.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/reset-password` |`xref:user-api.adoc#invalidate-user-session[**POST** /tspublic/v1/user/session/invalidate]` + Invalidates a user session.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/force-logout` |`xref:user-api.adoc#deactivate-user[**POST** /tspublic/v1/user/inactivate]` + Deactivates a user account.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/deactivate` |`xref:user-api.adoc#user-sync[**POST** /tspublic/v1/user/sync]` + Synchronizes user and group properties from an external database with the user data on ThoughtSpot.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# + ThoughtSpot Software [version noBackground]#6.0.x# +|`POST /api/rest/2.0/users/import` |`xref:user-api.adoc#assignUserToGroups[**POST** /tspublic/v1/user/{userid}/groups]` + Assigns a user to the specified user groups.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/{user_identifier}/update` |`xref:user-api.adoc#getGroupsUser[**GET** /tspublic/v1/user/{userid}/groups]` + Gets details of the user groups associated with a specific user.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/search` |`xref:user-api.adoc#editGroupsforUser[**PUT** /tspublic/v1/user/{userid}/groups]` + Updates the user group data for a specific user.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/{user_identifier}/update` |`xref:user-api.adoc#removeUserGroupAssoc[**DELETE** /tspublic/v1/user/{userid}/groups]` + Removes a user from the specified user groups.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.2.1# +|`POST /api/rest/2.0/users/{user_identifier}/update` |===== -- diff --git a/modules/ROOT/pages/user-api.adoc b/modules/ROOT/pages/user-api.adoc index b2a284104..bb2368998 100644 --- a/modules/ROOT/pages/user-api.adoc +++ b/modules/ROOT/pages/user-api.adoc @@ -8,6 +8,13 @@ The User APIs allow you to programmatically create, update, and administer ThoughtSpot users. +[IMPORTANT] +==== +The REST API v1 framework is deprecated. Existing integrations that use the v1 user endpoints continue to function without disruption, but ThoughtSpot strongly recommends migrating to the REST API v2 `users` endpoints for all new implementations. Each section on this page notes its v2 replacement. + +For more information, see xref:rest-api-v2-reference.adoc[REST API v2 Reference] and xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2 comparison]. +==== + == Supported operations include::{path}/user-api-list.adoc[] @@ -20,6 +27,11 @@ If you have a multi-tenant instance with Orgs feature enabled, the cluster admin [#create-user] == Create a user +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/create` for new implementations. +==== + To programmatically create a user account in the ThoughtSpot system, send a POST request to `/tspublic/v1/user/` API endpoint. Using this API, you can create a user and assign a user to a group. [NOTE] @@ -181,6 +193,11 @@ Unauthorized user addition to an org [#update-user] == Update user details +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/{user_identifier}/update` for new implementations. +==== + To modify an existing user account, send a `PUT` request to the `/tspublic/v1/user/{userid}` endpoint. This API you to modify the following properties of a user object: @@ -417,6 +434,11 @@ Response Code == Add or modify the email address of a user +[NOTE] +==== +[tag redBackground]#DEPRECATED# REST API v2 does not provide a dedicated endpoint for updating an email address. Use `POST /api/rest/2.0/users/{user_identifier}/update` and set the `email` property in the request body. +==== + To add or modify the email address of a user, send a `PUT` request to the `/tspublic/v1/user/email` API endpoint. @@ -475,6 +497,11 @@ Response Code [#addOrg] == Add users to an Org + +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/{user_identifier}/update` with the `org_identifiers` property to set the Orgs for a single user, or `POST /api/rest/2.0/orgs/{org_identifier}/update` to manage the membership of an Org. +==== To add one or several users to an org, send a `POST` request to the `POST /tspublic/v1/user/addtoorg` API endpoint. @@ -534,11 +561,16 @@ Response Code [#get-user-details] == Get user details +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/search` for new implementations. +==== + 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. [NOTE] ==== -If you want to get a list of object headers associated with a user or user group, you can use the `xref:metadata-api.adoc#object-header[GET /tspublic/v1/metadata/listobjectheaders]` API. +If you want to get a list of object headers associated with a user or user group, you can use the `xref:metadata-api.adoc#object-header[GET /tspublic/v1/metadata/listobjectheaders]` API. This endpoint is also deprecated; use `POST /api/rest/2.0/metadata/search` for new implementations. ==== === Resource URL @@ -663,6 +695,11 @@ If no `userid` or `name` attribute is specified, the API returns a response with [#deactivate-user] == Deactivate a user account +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/deactivate` for new implementations. +==== + To deactivate a user account, send a `POST` request to the `/tspublic/v1/user/inactivate` API endpoint. === Resource URL @@ -721,6 +758,11 @@ Note the user ID and auth token string. You will need this information to re-act [#activate-user] == Activate a user account +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/activate` for new implementations. +==== + To activate a user account that is currently inactive, send a `POST` request to the `/tspublic/v1/user/activate` API endpoint. [IMPORTANT] @@ -788,6 +830,11 @@ Response Code [#invalidate-user-session] == Invalidate a user session +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/force-logout` for new implementations. +==== + After a password of a user account is reset, you may want to invalidate a user session and force the user to re-login with the new password. To invalidate a user session, you can send a `POST` request to the `/tspublic/v1/user/session/invalidate` endpoint. @@ -854,6 +901,11 @@ Response Code [#delete-user] == Delete a user account + +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/{user_identifier}/delete` for new implementations. +==== To remove a user from the ThoughtSpot system, send a `DELETE` request to the `/tspublic/v1/user/{userid}` API endpoint. === Resource URL @@ -912,6 +964,11 @@ Response Code [#user-list] == Get a list of users and groups +[NOTE] +==== +[tag redBackground]#DEPRECATED# REST API v2 does not provide a combined users-and-groups listing. Use `POST /api/rest/2.0/users/search` and `POST /api/rest/2.0/groups/search` instead. The `users/search` response includes the `user_groups` property for each user, so the group associations do not require a separate lookup. +==== + To get a list of users and groups available in the ThoughtSpot system and view details of their inter-dependencies, use the `/tspublic/v1/user/list` API endpoint. === Resource URL @@ -1079,6 +1136,11 @@ Indicates if the user or user group needs to be activated. If the user or user g [#change-pwd] == Change password + +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/change-password` for new implementations. +==== To change the password of a ThoughtSpot user account, send a `POST` request to the `/tspublic/v1/user/updatepassword` endpoint. === Resource URL @@ -1131,6 +1193,11 @@ Response Code [#resetpassword] == Reset password + +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/reset-password` for new implementations. +==== To reset the password of a ThoughtSpot user account, send a `POST` request to the `/tspublic/v1/user/resetpassword` API endpoint. @@ -1189,6 +1256,11 @@ Response Code [#updatepreference-api] == Update a user profile + +[NOTE] +==== +[tag redBackground]#DEPRECATED# REST API v2 does not provide a dedicated endpoint for user preferences. Use `POST /api/rest/2.0/users/{user_identifier}/update` and set the corresponding user properties in the request body. +==== To update the profile settings of a ThoughtSpot user programmatically, send a `PUT` request to the `/tspublic/v1/user/updatepreference` endpoint. The `/tspublic/v1/user/updatepreference` API allows you to modify the following attributes of a ThoughtSpot user profile: @@ -1337,6 +1409,11 @@ The allowed values are: [#transfer-ownership] == Transfer ownership +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/security/metadata/assign`, which assigns a new author to one or several metadata objects. +==== + When a user is removed from the ThoughtSpot application, you may want to transfer objects from the deleted user account to the account. Administrators can programmatically transfer the ownership of one or several objects from one ThoughtSpot user to another via the `/tspublic/v1/user/transfer/ownership` API endpoint. === Resource URL @@ -1397,6 +1474,11 @@ Response Code [#user-sync] == Synchronize principals + +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/import` for new implementations. +==== 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. @@ -1544,6 +1626,13 @@ The preceding example covers user objects (with emails), group objects, and thei [#assignUserToGroups] == Assign a user to groups +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/{user_identifier}/update` with the `group_identifiers` property. + +IMPORTANT: The v2 `group_identifiers` property is declarative and replaces the entire set of groups assigned to the user. Unlike this v1 endpoint, it does not add to the existing assignments. To add a group, include the user's current groups along with the new one in the request. To retrieve the current assignments, use `POST /api/rest/2.0/users/search` and read the `user_groups` property. +==== + To assign a user to groups that exist in the Thoughtspot system, send a `POST` request to the `/tspublic/v1/user/{userid}/groups` API endpoint. === Resource URL @@ -1601,6 +1690,11 @@ Response Code [#getGroupsUser] == Get user group details for a specific user +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/search` and read the `user_groups` property in the response. +==== + To get a list of user groups associated with a user, send a `GET` request to the `/tspublic/v1/user/{userid}/groups` API endpoint. === Resource URL @@ -1726,6 +1820,11 @@ If the GET operation is successful, the API returns the following response: [#editGroupsforUser] == Update group association for a user +[NOTE] +==== +[tag redBackground]#DEPRECATED# Use `POST /api/rest/2.0/users/{user_identifier}/update` with the `group_identifiers` property, which replaces the entire set of groups assigned to the user. +==== + To update the user group data for a specific user, send a `PUT` request to the `/tspublic/v1/user/{userid}/groups` API endpoint. === Resource URL @@ -1783,6 +1882,13 @@ Response Code == Remove a user from user groups +[NOTE] +==== +[tag redBackground]#DEPRECATED# REST API v2 does not provide a dedicated endpoint for removing group assignments. Use `POST /api/rest/2.0/users/{user_identifier}/update` and pass the groups you want to retain in the `group_identifiers` property. + +IMPORTANT: Because `group_identifiers` replaces the entire set of groups assigned to the user, omitting a group removes it. Passing an empty array removes the user from all groups. +==== + To remove the existing group assignments for a user, send a `DELETE` request to the `/tspublic/v1/user/{userid}/groups` API endpoint. === Resource URL From ebe0f89bcbbd37375f53d5d51217d5ead4fca4ec Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 25 Aug 2026 14:09:53 +0530 Subject: [PATCH 2/2] removed v1 ref --- modules/ROOT/pages/api-user-management.adoc | 219 +++++++++++++++++--- 1 file changed, 189 insertions(+), 30 deletions(-) diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index 234232267..2ea23a4eb 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -8,9 +8,18 @@ To provide access to ThoughtSpot content or define privileges, you must add users and groups in ThoughtSpot. You can create user accounts and user groups in the ThoughtSpot UI or via REST API calls. +== Required permissions + +// TODO(verify): this permission list was carried over from the REST API v1 user +// documentation. Confirm it against the v2 endpoint privilege requirements. + +You must have administrator privileges to create, edit, and delete a user, assign users to groups, transfer objects from one user to another, and activate, deactivate, or log out a user. + +On a multi-tenant instance with the Orgs feature enabled, the cluster administrator can create a user and assign it to one or several Orgs. For more information about Orgs, see xref:orgs.adoc[Multi-tenancy with Orgs]. + == User creation and update -You can create users and update user profiles using xref:rest-api-reference.adoc#_user_management[REST API v1] or xref:rest-api-v2-reference.adoc#_users[v2 endpoints]. +You can create users and update user profiles using the xref:rest-api-v2-reference.adoc#_users[REST API v2 `users` endpoints]. While you can delete users, it is preferable to deactivate a user, which maintains the user's references within the system. @@ -19,6 +28,33 @@ When configuring xref:configure-saml.adoc[SAML SSO] in ThoughtSpot UI, you can s By default, ThoughtSpot sends e-mail messages to a new user and enables onboarding workflows when they log in for the first time, even when you are embedding ThoughtSpot content. To alter this behavior at a system-wide level, you need to xref:customize-email-settings.adoc[Customize the onboarding settings]. The user update API also allows setting onboarding experience values for an individual user. If you need to modify the default behavior beyond the available UI options, contact your ThoughtSpot team. +=== User account attributes + +A user account carries the following attributes. Set them with `POST /api/rest/2.0/users/create` or `POST /api/rest/2.0/users/{user_identifier}/update`, and read them with `POST /api/rest/2.0/users/search`: + +* Identity: `name` (the unique username), `display_name`, `email`, and `password`. +* Authentication: `account_type` records how the user authenticates. When you import users from an external server such as Active Directory or an IdP, ThoughtSpot assigns `account_type` automatically. For example, a user from an LDAP server is added as `LDAP_USER`. For IAMv2 users, the default is `OIDC_USER`. +// TODO(verify): the full set of valid account_type values was carried over from +// the REST API v1 usertype parameter. Only LOCAL_USER, SAML_USER, and OIDC_USER +// are attested in v2 examples in this repo. Confirm LDAP_USER and REMOTE_USER +// against the v2 OpenAPI spec. +* Status: `account_status`, such as `ACTIVE` or `INACTIVE`. For IAMv2 users, the response can also include `SUSPENDED`. See xref:api-user-management.adoc#_user_migration_to_iamv2[User migration to IAMv2]. +* Sharing: `visibility` controls whether other users and groups can share objects with this user. A user set to `SHARABLE` appears in the sharing dialog. +// TODO(verify): REST API v1 used DEFAULT and NON_SHARABLE for this attribute. +// Only SHARABLE is attested in v2 examples in this repo. Confirm the full set of +// v2 values against the OpenAPI spec. +* Membership: `group_identifiers` and `org_identifiers`. A user's privileges are determined by the groups they belong to. For example, a user assigned to a group with the `ADMINISTRATION` privilege has admin privileges. +* Content defaults: `home_liveboard_identifier` and `favorite_metadata`. + +For the filtering behavior and the exact values these attributes accept, see the following sections of xref:rest-api-v2-users-search.adoc[Search users]: + +* xref:rest-api-v2-users-search.adoc#_account_type_and_account_status[account_type and account_status] +* xref:rest-api-v2-users-search.adoc#_visibility[visibility] +* xref:rest-api-v2-users-search.adoc#_group_identifiers[group_identifiers] +* xref:rest-api-v2-users-search.adoc#_org_identifiers[org_identifiers] + +For the complete request schema, see the +++users/create+++ and +++users/{user_identifier}/update+++ playground entries. For the full response structure, see xref:rest-api-v2-users-search.adoc[Search users]. + [NOTE] ==== ThoughtSpot supports local management of users. For initial development and testing purposes, you can create users in ThoughtSpot and manage their profiles locally. However, in large production environments, avoid creating local user profiles to reduce administration overhead. @@ -74,28 +110,23 @@ The common user state transitions include: ==== APIs for user state transitions To check the status of a user account, use one of the following API endpoints: -* +++POST /api/rest/2.0/users/search+++ (REST API v2) -* xref:user-api.adoc[GET /tspublic/v1/user/] (REST API v1) +* +++POST /api/rest/2.0/users/search+++ To create a user in the `SUSPENDED` state, use one of the following API endpoints: -* +++POST /api/rest/2.0/users/create+++ (Rest API v2) -* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1) +* +++POST /api/rest/2.0/users/create+++ To update user status from `ACTIVE` or `PENDING` to `SUSPENDED`, or reactivate a `SUSPENDED` user to the ACTIVE or PENDING state, use one of the following API endpoints: -* +++POST /api/rest/2.0/users/{user_identifier}/update+++ (Rest API v2) -* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1) +* +++POST /api/rest/2.0/users/{user_identifier}/update+++ To deactivate an `ACTIVE` user, use one of these API endpoints: -* +++POST /api/rest/2.0/users/deactivate+++ (Rest API v2) -* xref:user-api.adoc#deactivate-user[POST /tspublic/v1/user/inactivate] (Rest API v1) +* +++POST /api/rest/2.0/users/deactivate+++ To activate an `INACTIVE` user account, use one of these API endpoints: -* +++POST /api/rest/2.0/users/activate+++ (Rest API v2) -* xref:user-api.adoc#activate-user[POST /tspublic/v1/user/activate] (Rest API v1) +* +++POST /api/rest/2.0/users/activate+++ //// @@ -118,14 +149,12 @@ Administrators can manage the user account status for all users. For IAMv2 users To create a user: -* +++POST /api/rest/2.0/users/create+++ (Rest API v2) -* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1) +* +++POST /api/rest/2.0/users/create+++ To update user details: -* +++POST /api/rest/2.0/users/{user_identifier}/update+++ (Rest API v2) -* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1) +* +++POST /api/rest/2.0/users/{user_identifier}/update+++ [NOTE] ==== @@ -172,31 +201,76 @@ For more information, see the following pages: * link:https://docs.thoughtspot.com/cloud/latest/oidc-iamv2[Managing authentication with OIDC using IAMv2, window=_blank] * link:https://docs.thoughtspot.com/cloud/latest/okta-iam[IAMv2 documentation, window=_blank] +== User preferences + +A user profile carries a set of preferences that you can read with `POST /api/rest/2.0/users/search` and set with `POST /api/rest/2.0/users/{user_identifier}/update`: + +* `notify_on_share` + +__Boolean__. Whether the user receives an email notification when another user shares an Answer or Liveboard with them. + +* `show_onboarding_experience` + +__Boolean__. Whether the user sees the guided onboarding walkthrough. ThoughtSpot provides an interactive walkthrough that leads new users through a set of actions to help them get started. Users can turn the onboarding experience off and access it again later when they need assistance with the ThoughtSpot UI. + +* `onboarding_experience_completed` + +__Boolean__. Indicates whether the user has completed onboarding. + +* `preferred_locale` and `use_browser_language` + +Set the language of the ThoughtSpot UI and the date, number, and currency formats for the user. For the supported locale IDs, the interaction between these two parameters, and the endpoints that accept them, see xref:locale-setting.adoc#_set_locale_via_rest_api[Set locale via REST API]. + +// TODO(verify): REST API v1 documented that the user-preference endpoint could not +// modify the profile picture, the account password, or the Answer experience +// setting. Confirm whether the same limitations apply to the v2 update endpoint +// before restoring that statement. + +== Account activation and deactivation + +* To deactivate an active user account, use +++POST /api/rest/2.0/users/deactivate+++. A deactivated user cannot log in to their ThoughtSpot instance. +* To activate a deactivated account, use +++POST /api/rest/2.0/users/activate+++. +* To remove a user from the system entirely, use `POST /api/rest/2.0/users/{user_identifier}/delete`. + +== Password management + +ThoughtSpot provides two distinct password operations: + +* +++POST /api/rest/2.0/users/change-password+++ + +Allows a user to change the password of their own account. The request requires the current password. + +* +++POST /api/rest/2.0/users/reset-password+++ + +Allows an administrator to reset the password of a user account without knowing the current password. + +The `can_change_password` property in the `POST /api/rest/2.0/users/search` response indicates whether a given user is permitted to change their own password. + +After resetting a password, you may want to force the user to log in again with the new credentials. See xref:api-user-management.adoc#_user_sessions[User sessions]. + +== User sessions + +To invalidate the current sessions of one or several users and force them to log in again, use +++POST /api/rest/2.0/users/force-logout+++. +This is typically used after a password reset, or when revoking access to an instance. == User group creation and update -Groups can be created via xref:rest-api-v2-reference.adoc#_groups[REST API v2] or xref:rest-api-reference.adoc#_groups_and_privileges[REST API v1] API endpoint. +Groups can be created via the xref:rest-api-v2-reference.adoc#_groups[REST API v2 `groups` endpoints]. The xref:api-user-management.adoc#group-privileges[Group privileges] are set directly on groups, either during group creation or via a group update API call. == User association to groups -You can add users to specific groups when creating a user or group via REST API endpoints. +You can add users to specific groups when creating a user or group via REST API endpoints. The association can be set from either side of the relationship: -The REST API v1 xref:group-api.adoc#addMembers[group/addmemberships] endpoint allows adding multiple users to multiple groups in a single request. +* From the user: `POST /api/rest/2.0/users/{user_identifier}/update` with the `group_identifiers` property, which takes an array of group names or GUIDs. +* From the group: `POST /api/rest/2.0/groups/{group_identifier}/update` with the `user_identifiers` property, which takes an array of usernames or user GUIDs. -To get a list of users assigned to a group, you can use the +++POST /api/rest/2.0/groups/search+++ v2 endpoint or the xref:group-api.adoc#get-usersInGroup[/tspublic/v1/group/{groupid}/users] v1 endpoint. +[IMPORTANT] +==== +Both `group_identifiers` and `user_identifiers` are declarative: the array you send replaces the entire existing set of associations rather than adding to it. -To remove a user from a group, use the update group REST v2 endpoint, or the following REST API v1 endpoints: +* To add an association, send the current members along with the new one. +* To remove an association, send the set you want to retain and omit the rest. Sending an empty array removes all associations. +* To read the current associations before updating them, use `POST /api/rest/2.0/users/search` (the `user_groups` property) or `POST /api/rest/2.0/groups/search` (the `users` property). +==== -* xref:group-api.adoc#delete-user-assoc[POST /tspublic/v1/group/{groupid}/user/{userid}] + -removes a user from a specific group -* xref:group-api.adoc#removeMembers[POST /tspublic/v1/group/removememberships] + -removes a list of users from many groups at once. +To get a list of users assigned to a group, use the +++POST /api/rest/2.0/groups/search+++ endpoint. -== Access control (sharing) -Access to objects is determined by content *shared* directly to the user or the groups they belong to. It is easier to manage and audit sharing through groups rather than object sharing at the individual user level. - -Users can share objects or modify sharing properties through the UI or via an API call to the `POST /api/rest/2.0/security/metadata/share` or xref:security-api.adoc#share-object[/tspublic/v1/security/share] endpoint. +Groups can also belong to other groups. Use the `sub_group_identifiers` property to manage nested groups. A group inherits the privileges of its parent group. [#group-privileges] == Group privileges @@ -211,7 +285,7 @@ include::{path}/group-privileges.adoc[] [NOTE] ==== -ThoughtSpot also has a default group called `All`. When you create new users in ThoughtSpot, they are automatically added to `All`. By default, the members of the `All` group do not have permission to download or upload data. To add these privileges, you can use the Group API endpoints. +ThoughtSpot also has a default group called `All`. When you create new users in ThoughtSpot, they are automatically added to `All`. By default, the members of the `All` group do not have permission to download or upload data. To add these privileges, use `POST /api/rest/2.0/groups/{group_identifier}/update`. ==== == Roles @@ -228,4 +302,89 @@ When creating or updating a group using the REST API v2 endpoints, use the `role Roles must be available before they can be assigned. Use the xref:roles-api.adoc[Roles API] to create roles programmatically before calling the group create or update endpoints. ==== -For a complete list of available privileges and role categories, see xref:roles.adoc[Role-based access control]. \ No newline at end of file +For a complete list of available privileges and role categories, see xref:roles.adoc[Role-based access control]. + +== Orgs and user assignment + +On instances with the Orgs feature enabled, each user belongs to one or several Orgs. + +* To set the Orgs for a single user, use `POST /api/rest/2.0/users/{user_identifier}/update` with the `org_identifiers` property, which takes an array of Org names or IDs. +* To manage the membership of an Org, use `POST /api/rest/2.0/orgs/{org_identifier}/update`. + +If you do not specify `org_identifiers` when creating a user, ThoughtSpot assigns the user to the Org context from which the API request was sent. + +For more information, see xref:orgs.adoc[Multi-tenancy with Orgs]. + +== Synchronize users and groups from an external directory + +To synchronize user accounts and user groups from an external database such as LDAP or Active Directory with ThoughtSpot, use +++POST /api/rest/2.0/users/import+++ for users and `POST /api/rest/2.0/groups/import` for groups. + +// TODO(verify): the reconciliation behavior described below was carried over from +// the REST API v1 user/sync endpoint. It is NOT confirmed for v2 users/import. +// In particular, confirm whether v2 import deletes principals that are absent from +// the supplied list, and what the request parameters are named, before relying on +// this section. See the users/import playground entry for the authoritative schema. +The request takes the set of principals that exist in the external database. ThoughtSpot reconciles its own users and groups against that set: + +* Principals present in the external list but not in ThoughtSpot are created. +* Principals present in both are updated so that their attributes in ThoughtSpot match those in the external list. This includes group membership. +* Principals present in ThoughtSpot but absent from the external list are deleted, unless the request specifies that deleted principals should be retained. + +[NOTE] +==== +Because the import operation can delete users and groups, run it first in a mode that reports the evaluated differences without applying them, review the result, and then apply the changes. +==== + +== Transfer object ownership + +When a user leaves the organization or their account is removed, you may want to transfer the objects they own to another user. Administrators can programmatically change the author of one or several metadata objects using +++POST /api/rest/2.0/security/metadata/assign+++. + +The endpoint assigns a new author to the specified objects, which transfers ownership from the current author to the target user. + +== Access control (sharing) +Access to objects is determined by content *shared* directly to the user or the groups they belong to. It is easier to manage and audit sharing through groups rather than object sharing at the individual user level. + +Users can share objects or modify sharing properties through the UI or via an API call to the `POST /api/rest/2.0/security/metadata/share` endpoint. + + +== REST API v2 endpoint reference + +The following REST API v2 endpoints cover the user, group, role, and Org management operations described on this page. + +[div tableContainer] +-- +[width="100%" cols="2,3"] +[options='header'] +|===== +|Operation| API endpoint +|Create a user|`POST /api/rest/2.0/users/create` +|Update a user, including group and Org assignment, preferences, and email address|`POST /api/rest/2.0/users/{user_identifier}/update` +|Get details of one or several users|`POST /api/rest/2.0/users/search` +|Delete a user|`POST /api/rest/2.0/users/{user_identifier}/delete` +|Activate a deactivated user account|`POST /api/rest/2.0/users/activate` +|Deactivate a user account|`POST /api/rest/2.0/users/deactivate` +|Change the password of your own account|`POST /api/rest/2.0/users/change-password` +|Reset the password of a user account|`POST /api/rest/2.0/users/reset-password` +|Log users out of their current sessions|`POST /api/rest/2.0/users/force-logout` +|Import users from an external directory|`POST /api/rest/2.0/users/import` +|Create a group|`POST /api/rest/2.0/groups/create` +|Update a group, including its users, sub-groups, privileges, and roles|`POST /api/rest/2.0/groups/{group_identifier}/update` +|Get details of one or several groups|`POST /api/rest/2.0/groups/search` +|Delete a group|`POST /api/rest/2.0/groups/{group_identifier}/delete` +|Import groups from an external directory|`POST /api/rest/2.0/groups/import` +|Create a role|`POST /api/rest/2.0/roles/create` +|Update a role|`POST /api/rest/2.0/roles/{role_identifier}/update` +|Get details of one or several roles|`POST /api/rest/2.0/roles/search` +|Delete a role|`POST /api/rest/2.0/roles/{role_identifier}/delete` +|Create an Org|`POST /api/rest/2.0/orgs/create` +|Update an Org, including its membership|`POST /api/rest/2.0/orgs/{org_identifier}/update` +|Get details of one or several Orgs|`POST /api/rest/2.0/orgs/search` +|Delete an Org|`POST /api/rest/2.0/orgs/{org_identifier}/delete` +|Change the author of one or several metadata objects|`POST /api/rest/2.0/security/metadata/assign` +|Share an object with users or groups|`POST /api/rest/2.0/security/metadata/share` +|Fetch the permissions of users or groups|`POST /api/rest/2.0/security/principals/fetch-permissions` +|Get details of the currently logged-in user|`GET /api/rest/2.0/auth/session/user` +|===== +-- + +For the complete request and response schema of each endpoint, see xref:rest-api-v2-reference.adoc[REST API v2 Reference].