user api v1 cleanup

.gitignore

@@ -118,10 +118,9 @@ docs/public/
 modules/**/generated/
 
 # PyCharm and Mac
-.idea
+.idea/*
 # Exception: share IntelliJ project dictionary so the team's
 # ThoughtSpot-specific terms don't show as spell-check typos.
-!.idea/
 !.idea/dictionaries/
 !.idea/dictionaries/*.xml
 .DS_store

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`
 |=====
 --

modules/ROOT/pages/roles-api.adoc

@@ -35,7 +35,7 @@ POST /tspublic/v1/role
 |Form parameter|Description
 |`name` |__String__. Name of the Role. The Role name string must be unique. Make sure the name string length does not exceed 48 characters.
 |`description`|__String__. Description of the Role. Make sure the description text does not exceed 124 characters.
-|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_privileges[Role privileges].
+|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_categories_and_privileges[Role privileges].
 |===
 
 === Example request
@@ -112,7 +112,7 @@ PUT /tspublic/v1/role/{role_identifier}
 |`role_identifier`|Path parameter|__String__. GUID of the role object to edit.
 |`name` |Form parameter|__String__. Name of the Role that you want to edit.
 |`description`|Form parameter|__String__. Description of the Role.
-|`privileges`|Form parameter|__Array of strings__. A JSON array of xref:roles.adoc#_role_privileges[Role privileges].
+|`privileges`|Form parameter|__Array of strings__. A JSON array of xref:roles.adoc#_role_categories_and_privileges[Role privileges].
 |===
 
 === Example request
@@ -193,7 +193,7 @@ POST /tspublic/v1/role/search
 
 NOTE: Cluster administrators with the `Super admin` Role can query Role objects for different Orgs. The cluster administrator can switch to an Org context via an API call to the `/tspublic/v1/session/orgs` endpoint, and then specify the Org name or ID in the API request.
 |`group_identifiers`|__Array of strings__. A JSON array of group names or GUIDs.
-|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_privileges[Role privileges].
+|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_categories_and_privileges[Role privileges].
 |===
 
 

modules/ROOT/pages/roles.adoc

@@ -36,7 +36,7 @@ This privilege grants administration permissions to manage users and groups on i
 * Authentication administration: __Can manage Authentication__
 * Application administration: __Can manage Application settings__
 
-For a complete list of Roles and privileges, see xref:roles.adoc#_role_privileges[Role categories and privileges].
+For a complete list of Roles and privileges, see xref:roles.adoc#_role_categories_and_privileges[Role categories and privileges].
 |====
 
 == Role assignment

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