auth and answer api

modules/ROOT/pages/authentication.adoc

@@ -87,13 +87,105 @@ Once the security rules are set, they are fixed for at least that user's session
 |||
 |===
 
+[#_enable_trusted]
+=== #Configure trusted authentication#
+To generate an access token, trusted authentication must be enabled on your ThoughtSpot instance.
+You can enable trusted authentication through the ThoughtSpot UI or the REST API v2.
+
+*Through the ThoughtSpot UI*
+
+The administrator must enable xref:trusted-auth-secret-key.adoc[Trusted authentication] on the
+*Develop* > *Customizations* > *Security settings* page.
+
+*Through the REST API v2*
+
+Before enabling trusted authentication through the REST API v2, check your existing
+authentication configuration.
+To retrieve the current authentication configuration at the
+cluster or Org level, send a request to the `POST /api/rest/2.0/auth/search` endpoint.
+
+==== Request parameters
+[width="100%" cols="1,4"]
+[options='header']
+|=====
+|Parameter|Description
+|`auth_type`
+|__String__. Type of authentication mechanism to configure. Currently, supports `TRUSTED_AUTH` only.
+
+|`scope`
+__Optional__
+|__String__. Select `CLUSTER` to retrieve only cluster-level settings, or `ORG` to retrieve only Org-level settings. If no selection is made, both cluster and Org-level settings are retrieved based on user permissions.
+|=====
+
+==== API request
+
+.cURL
+[source, cURL]
+----
+curl -X POST \
+--url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/search'  \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {AUTH_TOKEN}'
+    {
+    "auth_type": "TRUSTED_AUTH"
+    }'
+----
+
+
+If trusted authentication is not enabled, you can enable or disable it at the cluster or Org level by sending a request to the `POST /api/rest/2.0/auth/configure` endpoint.
+
+
+=== Request parameters
+[width="100%" cols="1,4"]
+[options='header']
+|=====
+|Parameter|Description
+|`auth_type`
+|__String__. Type of authentication mechanism to configure. Currently, supports `TRUSTED_AUTH` only.
+
+|`cluster_preferences`
+__Optional__
+|__Nullable__. `ENABLE` or `DISABLE` authentication for the cluster. When enabled, a new token is generated if one does not exist. When disabled, the existing cluster-level access token is revoked.
+
+|`org_preferences`
+__Optional__
+|__Nullable__. `ENABLE` or `DISABLE` authentication for a particular Org.  When enabled, a new org-level access token is generated if one does not exist. When disabled, the existing org-level access token is revoked.
+
+|`org_identifier`
+
+|=====
+
+==== API request
+
+.cURL
+[source, cURL]
+----
+curl -X POST \
+--url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/configure'  \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer {AUTH_TOKEN}
+    '{
+    "auth_type": "TRUSTED_AUTH",
+    "org_preferences": [
+        {
+        "org_identifier": "Test",
+        "auth_status": "ENABLED"
+        }
+        ]
+    }'
+----
+
+If the API request is successful, ThoughtSpot returns a 204 status code.
+
+
 [#_generate_a_full_access_token]
 === Generating a full access token
 To generate a full access token, send a `POST` request to the `/api/rest/2.0/auth/token/full` API endpoint with the required attributes.
 
 You can generate a token by providing a `username` and `password`, or by using a `secret_key`.
 
-To generate a `secret_key`, the administrator must enable xref:trusted-auth-secret-key.adoc[trusted authentication] on the **Develop** > **Customizations** > **Security Settings** page.
+To generate a `secret_key`, the administrator must enable xref:trusted-auth-secret-key.adoc[trusted authentication] on the **Develop** > **Customizations** > **Security Settings** page or through the APIs.
 
 After ThoughtSpot issues an authentication token, the user must include the token in the `Authorization` header of their subsequent API requests.
 
@@ -161,7 +253,7 @@ If the API request is successful, ThoughtSpot returns the authentication token t
 ==== API request with username and secret key
 To obtain an authentication token for a user, include `username` and `secret_key` in the API request. In a trusted authentication implementation, you can request tokens on behalf of users who require access to the ThoughtSpot content embedded in a third-party application.
 
-To request a token on behalf of another user, you need administrator privileges and a `secret key` that allows you to securely pass the authentication details of an embedded application user. The `secret key` is generated xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled on a ThoughtSpot instance].
+To request a token on behalf of another user, you need administrator privileges and a `secret_key` that allows you to securely pass the authentication details of an embedded application user. The `secret_key` is generated xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled on a ThoughtSpot instance].
 
 To get a trusted authentication token that grants full access to ThoughtSpot, send a `POST` request with `username`, `secret_key`, and other attributes to the `/api/rest/2.0/auth/token/full` endpoint:
 
@@ -172,7 +264,7 @@ To get a trusted authentication token that grants full access to ThoughtSpot, se
 |`username`
 |__String__. Username of the ThoughtSpot user. If the user is not available in ThoughtSpot, you can set the `auto_create` parameter to `true` to create a user just-in-time (JIT).
 |`secret_key`
-|__String__. The secret key string generated for your ThoughtSpot instance. The secret key is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance.
+|__String__. The `secret_key` string generated for your ThoughtSpot instance. The `secret_key` is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance.
 |`validity_time_in_sec` +
 __Optional__|__Integer__. Token expiry duration in seconds. The default duration is 300 seconds. You can set the token expiry duration to a higher value. API requests with an expired or invalid token result in an error. In such cases, REST clients must obtain a new token from ThoughtSpot and use it in their subsequent API calls.
 |`org_id` +
@@ -187,7 +279,7 @@ The following example shows the request body with `username` and `secret_key`:
 [source,cURL]
 ----
 curl -X POST \
-  --url 'https://stage-grapes-champagne.thoughtspotstaging.cloud/api/rest/2.0/auth/token/full'  \
+  --url 'https://{ThoughtSpot-Host}api/rest/2.0/auth/token/full'  \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   --data-raw '{
@@ -298,7 +390,7 @@ To get a token that grants `read-only` access to a specific metadata object, sen
 |__String__. Username of the ThoughtSpot user. If the user is not available in ThoughtSpot, you can set the `auto_create` parameter to `true` to create a user just-in-time (JIT).
 
 |`secret_key`
-|__String__. The secret key string generated for your ThoughtSpot instance. The secret key is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance.
+|__String__. The `secret_key` string generated for your ThoughtSpot instance. The `secret_key` is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance.
 
 |`object_id`
 |__String__. GUID of the ThoughtSpot object.
@@ -542,7 +634,7 @@ For cookie-based authentication, make an API call to the `/api/rest/2.0/auth/ses
 |__String__. The password of the user account.
 
 |`org_identifier`
-|__String__. Name or ID of the Org. If no Org ID is specified, the user will be logged into the Org context of their previous session.
+|__String__. Name or ID of the Org. If no Org ID is specified, the user is logged into the Org context of their previous session.
 
 |`remember_me`
 __Optional__
@@ -772,13 +864,5 @@ curl -X POST \
 
 If the API request is successful, ThoughtSpot returns a 204 status code and ends the user session.
 
-////
-==== Response codes
 
-[options="header", cols="2,4"]
-|===
-|HTTP status code|Description
-|**204**|The user is logged out of ThoughtSpot
-|**500**|Failed operation
-|===
-////
+

modules/ROOT/pages/collections.adoc

@@ -235,6 +235,146 @@ curl -X POST \
 
 If the API request is successful, the objects in the Collection are replaced with the objects in this API request.
 
+== Share a Collection
+[NOTE]
+====
+Collections sharing via the security API is available from ThoughtSpot Cloud 26.6.0.cl.
+====
+
+To share a Collection with a user or group, send a `POST` request to the `POST /api/rest/2.0/security/metadata/share` endpoint with `metadata_type` set to `COLLECTION`.
+
+Collections support dual permissions that let you set independent access levels for the Collection and the objects within it.
+
+=== Permission fields
+
+[width="100%", cols="1,1,3"]
+[options='header']
+|=====
+|Field|Applies to|Description
+
+|`share_mode`|Collection |Controls access to the Collection itself — view, edit, or delete the Collection.
+Accepted values: `READ_ONLY`, `MODIFY`, `NO_ACCESS`.
+
+|`content_share_mode`|Collection content|Controls access to the objects within the Collection — Liveboards, Answers, Models, and nested Collections.
+Accepted values: `READ_ONLY`, `MODIFY`, `NO_ACCESS`.
+
+Only applicable when `metadata_type` is `COLLECTION`. If omitted, defaults to `READ_ONLY` (or `NO_ACCESS` when `share_mode` is `NO_ACCESS`).
+|=====
+
+=== Permission scenarios
+
+[width="100%", cols="1,1,1,2"]
+[options='header']
+|=====
+|Role|`share_mode`|`content_share_mode`|What the principal can do
+
+|`MODIFY`|`MODIFY`|Full control — manage the Collection and edit its contents
+|`MODIFY`|`READ_ONLY`|Manage the Collection structure but cannot edit objects within it
+|`READ_ONLY`|`MODIFY`|Edit objects within the Collection but cannot change the Collection itself
+|`READ_ONLY`|`READ_ONLY`|View the Collection and its contents only
+|=====
+
+=== Share a Collection (read-only)
+
+To share a Collection with a user in read-only mode, send the following request:
+
+[source,CURL]
+----
+curl -X POST \
+  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer {AUTH_TOKEN}' \
+  --data-raw '{
+  "metadata_type": "COLLECTION",
+  "metadata_identifiers": ["Sales reports"],
+  "permissions": [
+    {
+      "principal": {
+        "type": "USER",
+        "identifier": "name@example.com"
+      },
+      "share_mode": "READ_ONLY"
+    }
+  ],
+  "notification": {
+    "message": "I have shared the Sales reports collection with you.",
+    "notify_on_share": true
+  }
+}'
+----
+
+If the request is successful, the API returns the HTTP `204 No Content` status code.
+
+=== Share a Collection with dual permissions
+
+To give a user different levels of access to the Collection and its contents, set both `share_mode` and `content_share_mode`.
+
+[source,CURL]
+----
+curl -X POST \
+  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer {AUTH_TOKEN}' \
+  --data-raw '{
+  "metadata_type": "COLLECTION",
+  "metadata_identifiers": ["Marketing Analytics"],
+  "permissions": [
+    {
+      "principal": {
+        "type": "USER",
+        "identifier": "name@example.com"
+      },
+      "share_mode": "MODIFY",
+      "content_share_mode": "READ_ONLY"
+    },
+    {
+      "principal": {
+        "type": "USER_GROUP",
+        "identifier": "Marketing Team"
+      },
+      "share_mode": "READ_ONLY",
+      "content_share_mode": "READ_ONLY"
+    }
+  ],
+  "notification": {
+    "message": "Sharing the Marketing Analytics collection with your team.",
+    "notify_on_share": true
+  }
+}'
+----
+
+If the request is successful, the API returns the HTTP `204 No Content` status code.
+
+=== Remove Collection access
+
+To remove a user's access to a Collection, set `share_mode` to `NO_ACCESS`:
+
+[source,CURL]
+----
+curl -X POST \
+  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer {AUTH_TOKEN}' \
+  --data-raw '{
+  "metadata_type": "COLLECTION",
+  "metadata_identifiers": ["Confidential Reports"],
+  "permissions": [
+    {
+      "principal": {
+        "type": "USER",
+        "identifier": "former-member@example.com"
+      },
+      "share_mode": "NO_ACCESS"
+    }
+  ]
+}'
+----
+
+If the request is successful, the API returns the HTTP `204 No Content` status code.
+
 == Delete a Collection
 To remove an existing Collection, send a `POST` request to the `POST /api/rest/2.0/collections/delete` API endpoint.
 

modules/ROOT/pages/data-report-v2-api.adoc

@@ -459,7 +459,7 @@ To download Answer data via `/api/rest/2.0/report/answer` API, you need at least
 
 In the request body, specify the GUID or name of the Answer object as `metadata_identifier`.
 
-You can download the Answer data in the `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`.
+The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`.
 
 ==== Example
 
@@ -477,10 +477,46 @@ curl -X POST \
 
 [NOTE]
 ====
-* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension.
+* Exported files are automatically named after the Answer title, with the file extension appended based on the selected format.
 * HTML rendering is not supported for PDF exports of Answers with tables.
 ====
 
+
+Contact ThoughtSpot support to enable these enhanced settings for this API endpoint on your ThoughtSpot instance:
+
+* `personalised_view_identifier` [earlyAccess eaBackground]#Early Access# +
+Optional parameter to specify the GUID of the personalised view of the `PINNED` Answer object that you want to download.
+* `type` [earlyAccess eaBackground]#Early Access# +
+Used to distinguish between a saved answer and a pinned answer on a Liveboard. Setting this parameter to `PINNED` allows the API to
+accept the guid of a pinned Answer directly as the `metadata_identifier`. When
+exporting an Answer, all Liveboard-level filters, Runtime Filters, and Column
+Security Rules (CSR) are automatically applied to the export output.
+
+The `png_options` [earlyAccess eaBackground]#Early Access# support the following properties:
+
+[cols="1,1,3"]
+|===
+|Property |Type |Description
+
+|`x_resolution`
+|Number
+|Width of the exported PNG in pixels. +
+Valid range: `600px` to `3840px`.
+
+|`y_resolution`
+|Number
+|Height of the exported PNG in pixels. +
+Valid range: `600px` to `3840px`.
+
+|`scaling`
+|Integer
+|Display scale percentage for objects rendered in the image. Adjusts the relative
+size of visual elements without cropping the image. +
+Valid range: `80%` to `500%`.
+|===
+
+You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need.
+
 [#exportSpotterData]
 ==== Export data generated from Spotter APIs
 To export results generated from Spotter APIs such as  `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body.
@@ -504,7 +540,7 @@ curl -X POST \
 
 * `session_identifier` refers to session ID returned in the Spotter API response.
 * `generation_number` indicates the Answer generation number.
-* `file_format`  specifies the format of the output. You can export the Spotter-generated data as PNG or CSV file. By default, the API exports this data in PNG file format.
+* `file_format`  specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format.
 
 ===== API Response