merging lb split and v1 api changes

modules/ROOT/pages/api-changelog.adoc

@@ -263,11 +263,11 @@ The SDK includes the following new features and enhancements in Liveboard embedd
 
 `liveboardGutter` embed config property::
 A new `liveboardGutter` property is available on `LiveboardViewConfig`. Use this property to set the gutter spacing between tiles on an embedded Liveboard.
-For more information, see xref:embed-pinboard.adoc#liveboard-gutter[Set Liveboard tile gutter]
+For more information, see xref:customize-liveboard-layout.adoc#liveboard-gutter[Set Liveboard tile gutter]
 
 12-column layout for Liveboard tile positioning::
 A new embed config property is available on `LiveboardViewConfig` to always use a 12-column grid layout for Liveboard tile positioning. When enabled, tile placement and sizing follow a fixed 12-column grid regardless of the Liveboard's default layout settings.
-For more information, see xref:embed-pinboard.adoc#force-12col-layout[12-column layout in embedded Liveboards]
+For more information, see xref:customize-liveboard-layout.adoc#force-12col-layout[12-column layout in embedded Liveboards]
 
 New host events for the Liveboard edit page::
 * `HostEvent.OpenAddFilterModal` +
@@ -316,7 +316,7 @@ Enables compact header layout in embedded Liveboards.
 *  `coverAndFilterOptionInPDF` +
 Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal.
 * `isLiveboardMasterpiecesEnabled` +
-Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature.
+Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature.
 * `isEnhancedFilterInteractivityEnabled` +
 Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard.
 
@@ -387,7 +387,7 @@ Trigger a manual cache refresh from the host application.
 * `Action.RefreshLiveboardBrowserCache` +
 Action ID to show or hide the cache refresh button.
 
-For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh].
+For more information, see xref:liveboard-data-downloads.adoc#liveboard-data-cache[Enable Liveboard refresh].
 
 |[tag greenBackground]#NEW# a|
 [discrete]
@@ -1731,7 +1731,7 @@ For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources
 |[tag greenBackground]#NEW#|
 For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab.
 
-For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs].
+For more information, see xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs].
 
 |[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects:
 

modules/ROOT/pages/api-user-management.adoc

@@ -10,20 +10,43 @@ To provide access to ThoughtSpot content or define privileges, you must add user
 
 == 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 user endpoints].
 
 While you can delete users, it is preferable to deactivate a user, which maintains the user's references within the system.
 
 When configuring xref:configure-saml.adoc[SAML SSO] in ThoughtSpot UI, you can select the *Automatically add SAML users to ThoughtSpot upon first authentication* option, which will use the values in the SAML assertion to create a user if they do not already exist on ThoughtSpot. ThoughtSpot can also add users to groups sent within the SAML assertion. To enable and configure the SAML group attributes, contact your ThoughtSpot team.
 
 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.
+To specify whether an activation email is sent to a new user, set the `trigger_activation_email` parameter in the `POST /api/rest/2.0/users/create` request.
 
 [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.
 ====
 
+=== Required privileges
+To create, edit, or delete users, assign users to groups, transfer objects from one user to another, or activate, deactivate, or log out users, you need administrator privileges (`ADMINISTRATION`).
+
+If Role-Based Access Control (RBAC) is enabled on your instance, the `USER_ADMINISTRATION` (*Can manage users*) privilege is required. On instances with Orgs, this privilege allows managing users only within the Org context of the API request. For more information, see xref:roles.adoc[Role-based access control].
+
+=== User attributes
+Note the following points about user attributes:
+
+* *Username*: The username must be unique. An API request to create a user with a username that already exists returns an error.
+* *Account type*: The `account_type` attribute indicates how the user was created and how the user authenticates. Valid values are:
+** `LOCAL_USER`: A user created and authenticated locally in ThoughtSpot. This is the default account type.
+** `LDAP_USER`: A user imported from an LDAP server.
+** `SAML_USER`: A user authenticated through SAML SSO.
+** `OIDC_USER`: A user authenticated through OpenID Connect (OIDC).
+** `REMOTE_USER`: A user authenticated by an external system.
++
+When users are imported from an external server, such as an LDAP server or an IdP, ThoughtSpot assigns the account type automatically. For example, a user imported from an LDAP server is added as `LDAP_USER`.
+* *Visibility*: The `visibility` attribute determines whether other users can share objects with the user. By default, users are set to `SHARABLE`, which allows other users and groups to share objects with them. To prevent other users from finding the user and sharing objects with them, set `visibility` to `NON_SHARABLE`. In multi-tenant deployments, users are commonly set to `NON_SHARABLE`.
+
+=== Password reset
+After you reset a user's password with the `POST /api/rest/2.0/users/reset-password` endpoint, you can log the user out of their active sessions by using the `POST /api/rest/2.0/users/force-logout` endpoint. The user must then log in again with the new password.
+
 
 ////
 === User account status
@@ -75,27 +98,22 @@ The common user state transitions include:
 To check the status of a user account, use one of the following API endpoints:
 
 * +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fsearch-user">POST /api/rest/2.0/users/search</a>+++  (REST API v2)
-* xref:user-api.adoc[GET /tspublic/v1/user/] (REST API v1)
 
 To create a user in the `SUSPENDED` state, use one of the following API endpoints:
 
 * +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fcreate-user">POST /api/rest/2.0/users/create</a>+++ (Rest API v2)
-* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1)
 
 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:
 
 * +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fupdate-user">POST /api/rest/2.0/users/{user_identifier}/update</a>+++ (Rest API v2)
-* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1)
 
 To deactivate an `ACTIVE` user, use one of these API endpoints:
 
 * +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fdeactivate-user">POST /api/rest/2.0/users/deactivate</a>+++ (Rest API v2)
-* xref:user-api.adoc#deactivate-user[POST /tspublic/v1/user/inactivate] (Rest API v1)
 
 To activate an `INACTIVE` user account, use one of these API endpoints:
 
 * +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Factivate-user">POST /api/rest/2.0/users/activate</a>+++ (Rest API v2)
-* xref:user-api.adoc#activate-user[POST /tspublic/v1/user/activate] (Rest API v1)
 ////
 
 
@@ -112,19 +130,17 @@ ThoughtSpot is gradually migrating its users to link:https://docs.thoughtspot.co
 
 * The `email` attribute is mandatory when creating a user in ThoughtSpot Okta. ThoughtSpot recommends that users provide a valid email address during user creation.
 * You must set a password during user creation if you do not want to trigger an activation email.
-* The default value for `usertype` will be `OIDC_USER`.
+* The default value for `account_type` will be `OIDC_USER`.
 
 Administrators can manage the user account status for all users. For IAMv2 users, the API response for the following APIs will also include `SUSPENDED` as a user state:
 
 To create a user:
 
-* +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fcreate-user">POST /api/rest/2.0/users/create</a>+++ (Rest API v2)
-* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1)
+* +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fcreate-user">POST /api/rest/2.0/users/create</a>+++
 
 To update user details:
 
-* +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fupdate-user">POST /api/rest/2.0/users/{user_identifier}/update</a>+++ (Rest API v2)
-* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1)
+* +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fupdate-user">POST /api/rest/2.0/users/{user_identifier}/update</a>+++
 
 [NOTE]
 ====
@@ -172,28 +188,52 @@ For more information, see the following pages:
 
 
 == 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 group endpoints].
+
+To create, edit, or delete groups, you need administrator privileges. If RBAC is enabled on your instance, the `GROUP_ADMINISTRATION` (*Can manage groups*) privilege is required. To assign Roles to a group or remove Roles from a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges.
 
 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.
+=== Group hierarchy
+ThoughtSpot supports hierarchical groups. You can create a parent group and add other groups to it as sub-groups. For example, you can create a parent group called `Site` and add your tenant groups to it. Sub-groups inherit the privileges of the parent group.
 
-The REST API v1 xref:group-api.adoc#addMembers[group/addmemberships] endpoint allows adding multiple users to multiple groups in a single request.
+To add sub-groups to a group or remove sub-groups from it, use the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group">POST /api/rest/2.0/groups/{group_identifier}/update</a>+++ endpoint. Removing a sub-group from a group removes only the association; it does not delete the sub-group from ThoughtSpot.
 
-To get a list of users assigned to a group, you can use the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fsearch-user-groups">POST /api/rest/2.0/groups/search</a>+++ v2 endpoint or the xref:group-api.adoc#get-usersInGroup[/tspublic/v1/group/{groupid}/users] v1 endpoint.
+== User association to groups
+You can add users to specific groups when creating a user or group via REST API endpoints. When you assign a user to a group, the user inherits the privileges and Roles assigned to that group.
+
+To add users to an existing group or remove users from it, use the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group">POST /api/rest/2.0/groups/{group_identifier}/update</a>+++ endpoint with the `user_identifiers` parameter and the `ADD`, `REMOVE`, or `REPLACE` operation. To update the groups of a single user, use the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fupdate-user">POST /api/rest/2.0/users/{user_identifier}/update</a>+++ endpoint with the `group_identifiers` parameter.
 
-To remove a user from a group, use the update group REST v2 endpoint, or the following REST API v1 endpoints:
+Removing a user from a group removes only the group association; it does not delete the user from ThoughtSpot. To delete a user, use the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fdelete-user">POST /api/rest/2.0/users/{user_identifier}/delete</a>+++ endpoint.
 
-* 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 +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fsearch-user-groups">POST /api/rest/2.0/groups/search</a>+++ 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.
+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.
+
+Note the following points about sharing objects via REST API:
+
+* You can share the following types of objects: Liveboards, visualizations, Answers, Models, Views, Connections, and Collections.
+* To share an object, you must have edit access to the object.
+* The `share_mode` attribute can be set to `READ_ONLY` (*Can view*), `MODIFY` (*Can edit*), or `NO_ACCESS`. Setting `share_mode` to `NO_ACCESS` removes any access previously granted to a user or group.
+* To send a share notification to the users and groups with whom the object is shared, set `notify_on_share` to `true`.
+* To make a shared Liveboard or Answer discoverable, set `has_lenient_discoverability` to `true`.
+
+To audit access, use the `POST /api/rest/2.0/security/metadata/fetch-permissions` endpoint to get the users and groups that have access to an object, or the `POST /api/rest/2.0/security/principals/fetch-permissions` endpoint to get the objects a user or group can access.
+
+For more information and examples, see xref:access-control-sharing.adoc[Access control and sharing].
+
+=== Sharing a visualization
+Note the following points about sharing a visualization:
+
+* Sharing a visualization implicitly shares the entire Liveboard with the recipient.
+* The object permissions set for a shared visualization also apply to the Liveboard, unless they are overridden by another API request or in the UI.
+* If email notifications for object sharing are enabled, the recipient receives a notification with a link to the shared visualization. Although this link opens the shared visualization, the recipient can also access other visualizations on the Liveboard.
+
+=== Sharing a Collection
+Collections support separate permissions for the Collection and for the objects within it. For more information, see xref:collections.adoc#_share_a_collection[Share a Collection].
 
 [#group-privileges]
 == Group privileges
@@ -222,7 +262,7 @@ When creating or updating a group using the REST API v2 endpoints, use the `role
 
 [NOTE]
 ====
-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.
+Roles must be available before they can be assigned. Use the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fcreate-role[`POST /api/rest/2.0/roles/create`] endpoint 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].

modules/ROOT/pages/audit-logs.adoc

@@ -43,10 +43,9 @@ Error Message: Cannot use first or last name in the password.","userId":"e3dc495
 Org ID if your ThoughtSpot application instance has Orgs.
 
 == Fetch logs via API
-To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. You can use any of the following APIs:
+To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. Use the following API endpoint:
 
-* +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Flog%2Ffetch-logs">POST /api/rest/2.0/logs/fetch</a>+++ (Recommended)
-* xref:logs-api.adoc[GET /tspublic/v1/logs/topics/{topic}] (REST API v1)
+* +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Flog%2Ffetch-logs">POST /api/rest/2.0/logs/fetch</a>+++
 
 On Orgs-enabled clusters, the API fetches security logs for the current Org text. However, the administrator of the primary Org (Org 0) can fetch logs not just for the primary Org, but also for all other Orgs if the `get_all_logs` parameter is set to `true` in the API request.
 

modules/ROOT/pages/authentication.adoc

@@ -972,6 +972,17 @@ If the API request is successful, ThoughtSpot returns the following response:
 |**500**|Failed operation
 |===
 ////
+[#switch-org]
+== Switching Org context
+On ThoughtSpot instances with Orgs, only cluster administrators and users who belong to more than one Org can switch between Orgs.
+
+For REST API v2 requests, the Org context is determined by the session or token used in the request. To send API requests in a different Org:
+
+* For cookie-based authentication, log in again by sending a request to the `/api/rest/2.0/auth/session/login` endpoint with the ID or name of the Org in the `org_identifier` attribute.
+* For token-based authentication, request a new token with the ID of the Org in the `org_id` attribute, or use a <<multi-org-tokens,multi-Org token>>.
+
+To view the Org context of the current session and the Orgs available to the user, send a request to the `/api/rest/2.0/auth/session/user` endpoint and check the `current_org` and `orgs` properties in the API response. For more information, see <<_viewing_session_information,Viewing session information>>.
+
 == Logging out of a session
 
 To log out of your current session, send a `POST` request to the `/api/rest/2.0/auth/session/logout` API endpoint.
@@ -986,6 +997,8 @@ curl -X POST \
   -H 'Authorization: Bearer {AUTH_TOKEN}'
 ----
 
+If you send the logout request as an AJAX call from a browser with cookie-based authentication, include credentials in the request so that the session cookie is sent. For example, set `xhrFields: { withCredentials: true }` in a jQuery AJAX request, or `credentials: 'include'` in a Fetch API request.
+
 === API response
 
 If the API request is successful, ThoughtSpot returns a 204 status code and ends the user session.