openapi: 3.0.0
info:
title: ThoughtSpot Public REST 10.1.0.cl Authentication API
version: '2.0'
servers:
- url: '{base-url}'
variables:
base-url:
default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: Authentication
paths:
/api/rest/2.0/auth/configure:
post:
operationId: configureAuthSettings
description: "\n <span class=\"since-beta-tag\">Version: 26.6.0.cl or later</span>\n\n<span class=\"since-beta-tag\">Version: 26.6.0.cl or later</span>\n\nEnables or disables authentication at cluster or org level for the specified auth type. Currently supports `TRUSTED_AUTH`.\n\n#### Required privileges\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) or `CONTROL_TRUSTED_AUTH` (**Can Enable or Disable Trusted Authentication**) privilege. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled, the `CONTROL_TRUSTED_AUTH` privilege is required.\n\n#### Usage guidelines\n\nUse `cluster_preferences` to enable or disable authentication at the cluster level. Cluster-level settings can only be configured from the Primary Org.\n- `ENABLED` — Generates a new access token if one does not exist. An existing token is preserved.\n- `DISABLED` — Revokes the existing cluster-level access token.\n\nUse `org_preferences` to enable or disable authentication for one or more Orgs. Each entry must include an `org_identifier` (unique ID or name) and an `auth_status`. Org-level configuration requires the per-Org authentication feature to be enabled on your instance.\n- `ENABLED` — Generates a new org-level access token if one does not exist.\n- `DISABLED` — Revokes the existing org-level access token for that Org.\n\nBoth `cluster_preferences` and `org_preferences` are optional. Omitting a field leaves the corresponding settings unchanged. If both are omitted, the API returns `204 No Content` without making any changes.\n\n**Note**: Cluster-level and org-level settings are independent of each other. Enabling or disabling one does not affect the other.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Authentication
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigureAuthSettingsRequest'
required: true
parameters: []
responses:
'204':
description: Trusted authentication settings configured successfully.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_request:
summary: Invalid request
value:
error:
message:
code: 10002
incident_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
trace_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
debug: At least one of cluster_preferences or org_preferences must be provided.
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized_access:
summary: Unauthorized access
value:
error:
message:
code: 10097
incident_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
trace_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
debug: Authentication required to configure authentication settings.
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
forbidden_access:
summary: Forbidden access
value:
error:
message:
code: 10023
incident_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
trace_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
debug: ADMINISTRATION or CONTROL_TRUSTED_AUTH privilege required to configure authentication settings.
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error
value:
error:
message:
code: 10038
incident_id_guid: d4e5f678-9012-3456-defa-456789012345
trace_id_guid: d4e5f678-9012-3456-defa-456789012345
debug: Unexpected server error while configuring authentication settings.
/api/rest/2.0/auth/session/user:
get:
operationId: getCurrentUserInfo
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nRetrieves details of the current user session for the token provided in the request header.\n\nAny ThoughtSpot user can access this endpoint and send an API request. The data returned in the API response varies according to user's privilege and object access permissions.\n\n**NOTE**: In ThoughtSpot, users with cluster administration privileges can access all Orgs by default. However, unless the administrator is explicitly added to an Org, the Orgs list in the session information returned by the API will include only the Primary Org. To include other Orgs in the API response, you must explicitly add the administrator to each Org in the Admin settings page in the UI or via user REST API.\n\n\n\n#### Endpoint URL\n"
tags:
- Authentication
parameters: []
responses:
'200':
description: Fetch current session user detail successful.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
example_1:
description: Current user info for an admin user in the primary org
value:
id: 59481331-ee53-42be-a548-bd87be6ddd4a
name: tsadmin
display_name: TS Admin
visibility: SHARABLE
author_id: 59481331-ee53-42be-a548-bd87be6ddd4a
can_change_password: true
complete_detail: true
creation_time_in_millis: 1699900000000
current_org:
id: 0
name: Primary
deleted: false
deprecated: false
account_type: LOCAL_USER
account_status: ACTIVE
email: tsadmin@example.com
example_2:
description: Current user info for a SAML user switched to a non-primary org
value:
id: 7e4c9f2a-8b5d-4a1e-9c3b-6d8e2f5a7b4c
name: sales_analyst
display_name: Sales Analyst
visibility: SHARABLE
author_id: 7e4c9f2a-8b5d-4a1e-9c3b-6d8e2f5a7b4c
can_change_password: false
complete_detail: true
creation_time_in_millis: 1699900000000
current_org:
id: 583464508
name: sales_org
deleted: false
deprecated: false
account_type: SAML_USER
account_status: ACTIVE
email: sales_analyst@example.com
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized_access:
summary: Unauthorized access
value:
error:
message:
code: 10097
incident_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
trace_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
debug: Authentication required to retrieve the current user information.
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error
value:
error:
message:
code: 10038
incident_id_guid: d4e5f678-9012-3456-defa-456789012345
trace_id_guid: d4e5f678-9012-3456-defa-456789012345
debug: Unexpected server error while retrieving current user information.
/api/rest/2.0/auth/session/token:
get:
operationId: getCurrentUserToken
description: "\n <span class=\"since-beta-tag\">Version: 9.4.0.cl or later</span>\n\nRetrieves details of the current session token for the bearer token provided in the request header.\n\nThis API endpoint does not create a new token. Instead, it returns details about the token, including the token string, creation time, expiration time, and the associated user.\n\nUse this endpoint to introspect your current session token, debug authentication issues, or when a frontend application needs session token details.\n\nAny ThoughtSpot user with a valid bearer token can access this endpoint and send an API request\n\n\n\n\n#### Endpoint URL\n"
tags:
- Authentication
parameters: []
responses:
'200':
description: Fetching token for current user successful.
content:
application/json:
schema:
$ref: '#/components/schemas/GetTokenResponse'
examples:
example_1:
description: Standard session token valid for 1 hour
value:
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_token_payload.signature
creation_time_in_millis: 1724277430000
expiration_time_in_millis: 1724281030000
valid_for_user_id: 59481331-ee53-42be-a548-bd87be6ddd4a
valid_for_username: tsadmin
example_2:
description: Short-lived session token valid for 5 minutes
value:
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_short_token_payload.signature
creation_time_in_millis: 1724277430000
expiration_time_in_millis: 1724277730000
valid_for_user_id: 7e4c9f2a-8b5d-4a1e-9c3b-6d8e2f5a7b4c
valid_for_username: sales_analyst
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized_access:
summary: Unauthorized access
value:
error:
message:
code: 10097
incident_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
trace_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
debug: Authentication required to retrieve the current session token.
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error
value:
error:
message:
code: 10038
incident_id_guid: d4e5f678-9012-3456-defa-456789012345
trace_id_guid: d4e5f678-9012-3456-defa-456789012345
debug: Unexpected server error while retrieving the current user session token.
/api/rest/2.0/auth/token/custom:
post:
operationId: getCustomAccessToken
description: "\n <span class=\"since-beta-tag\">Version: 10.4.0.cl or later</span>\n\nCreates an authentication token that provides values for the formula variables in the Row Level Security (RLS) rules for a given user. Recommended for use cases that require Attribute-based access control (ABAC) via RLS.\n\n#### Required privileges\n\nTo add a new user and assign privileges during auto-creation, the `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege is required. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled, the `CONTROL_TRUSTED_AUTH` (**Can Enable or Disable Trusted Authentication**) privilege and edit access to the data source are required.\n\nTo configure formula variables for all Orgs on your instance or the Primary Org, cluster administration privileges are required. Org administrators can configure formula variables for their respective Orgs. If Role-Based Access Control (RBAC) is enabled, users with the `CAN_MANAGE_VARIABLES` (**Can manage variables**) role privilege can also create and manage variables for their Org context.\n\n#### Usage guidelines\n\nYou 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 [Trusted authentication](https://developers.thoughtspot.com/docs/trusted-auth-secret-key) in the **Develop** > **Customizations** > **Security Settings** page.\n\n**Note**:\n* When both `password` and `secret_key` are included in the API request, `password` takes precedence.\n* If [Multi-Factor Authentication (MFA)](https://docs.thoughtspot.com/cloud/latest/authentication-local-mfa) is enabled on your instance, the API login request with `username` and `password` returns an error. You can switch to token-based authentication with `secret_key` or contact ThoughtSpot Support for assistance.\n\nThe token obtained from ThoughtSpot is valid for 5 minutes by default. You can configure the token expiration time as required.\n\n#### ABAC via RLS\n\nTo implement ABAC via RLS and assign security entitlements to users during session creation, generate a token with custom variable values. The values set in the authentication token are applied to the formula variables referenced in RLS rules at the table level, which determines the data each user can access based on their entitlements.\n\nThe variable values can be configured to persist for a specific set of Models in user sessions initiated with the token, allowing different RLS rules to be set for different data models. Once defined, the rules are added to the user's `variable_values` object, after which all sessions will use the persisted values.\n\nFor more information, see [ABAC via tokens Documentation](https://developers.thoughtspot.com/docs/abac-via-rls-variables).\n\n##### Formula variables\nBefore defining variable values, ensure the variables are created and available on your instance. To create a formula variable, you can use the **Create variable** (`/api/rest/2.0/template/variables/create`) REST API endpoint, with the variable `type` set as `Formula_Variable` in the API request.\n\nThe API doesn't support `\"persist_option\": \"RESET\"` and `\"persist_option\": \"NONE\"` when `variable_values` are defined in the request. If you are using `variable_values` for token generation, you must use other supported persist options such as `APPEND` or `REPLACE`.\n\nIf you want to use `RESET` or `NONE`, do not pass any `variable_values`. In such cases, `variable_values` will remain unaffected.\n\n#### Supported objects\n\nThe supported object type is `LOGICAL_TABLE`. When using `object_id` with `variable_values`, models are supported.\n\n#### Just-in-time provisioning\n\nFor [just-in-time user creation and provisioning](https://developers.thoughtspot.com/docs/just-in-time-provisioning), specify the following attributes in the API request:\n\n* `auto_create`\n* `username`\n* `display_name`\n* `email`\n* `groups`\n\nSet `auto_create` to `true` if the username does not exist in ThoughtSpot. If the username already exists in ThoughtSpot and `auto_create` is set to `true`, user properties such as display name, email, Org and group entitlements will not be updated with new values. Setting `auto_create` to `true` does not create formula variables. Hence, this setting will not be applicable to `variable_values`.\n\n#### Important point to note\nAll options in the token creation APIs that define user access to data in ThoughtSpot will take effect during token creation, not when the token is used for authentication. For example, `auto_create:true` will create the user when the authentication token is created. Persist options such as `APPEND` and `REPLACE` will persist `variable_values` on the user profile when the token is created.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Authentication
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomAccessTokenRequest'
required: true
parameters: []
responses:
'200':
description: ABAC token creation was successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AccessToken'
examples:
example_1:
description: Custom access token with variable values and APPEND persist option for an existing user
value:
id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_custom_token.signature
org:
id: 0
name: Primary
user:
id: 59481331-ee53-42be-a548-bd87be6ddd4a
name: analyst_user
creation_time_in_millis: 1724277430000
expiration_time_in_millis: 1724277730000
example_2:
description: Custom access token with variable values for a JIT-provisioned user
value:
id: 1a2b3c4d-5e6f-7890-abcd-ef1234567890
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_jit_custom_token.signature
org:
id: 1
name: SalesOrg
user:
id: 3f2e1d4c-9b8a-7e6f-5d4c-3b2a1e0f9d8c
name: new_sales_user@example.com
creation_time_in_millis: 1724278000000
expiration_time_in_millis: 1724278300000
'400':
description: Invalid request. This could be due to missing or incorrect parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_request:
summary: Invalid request
value:
error:
message:
code: 10002
incident_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
trace_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
debug: 'Invalid persistOption: ''APPEND''. Expected: ''RESET'' when resetOption is provided.'
'401':
description: Unauthorized access. The request could not be authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized_access:
summary: Unauthorized access
value:
error:
message:
code: 10097
incident_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
trace_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
debug: Invalid credentials. The provided secret key or password is incorrect.
'403':
description: Forbidden access. The user does not have permission to access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
forbidden_access:
summary: Forbidden access
value:
error:
message:
code: 10023
incident_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
trace_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
debug: Trusted authentication is not enabled for this cluster or org.
'409':
description: Conflict. A concurrent update to the same template variable was detected and the request could not be applied. Retry the request after serializing concurrent variable updates.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An unexpected error occurred on the server.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error
value:
error:
message:
code: 10038
incident_id_guid: d4e5f678-9012-3456-defa-456789012345
trace_id_guid: d4e5f678-9012-3456-defa-456789012345
debug: Unexpected server error while generating the custom access token.
security: []
/api/rest/2.0/auth/token/full:
post:
operationId: getFullAccessToken
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nGenerates an authentication token for creating a full session in ThoughtSpot for a given user. Recommended for use cases that do not require Attribute-based access control (ABAC) via Row Level Security (RLS).\n\n#### Usage guidelines\n\nYou can generate a token for a user by providing a `username` and `password`, or by using the `secret_key` generated for your instance. To generate a `secret_key`, the administrator must enable [Trusted authentication](https://developers.thoughtspot.com/docs/trusted-auth-secret-key) in the **Develop** > **Customizations** > **Security Settings** page.\n\n**Note**:\n* When both `password` and `secret_key` are included in the API request, `password` takes precedence.\n* If [Multi-Factor Authentication (MFA)](https://docs.thoughtspot.com/cloud/latest/authentication-local-mfa) is enabled on your instance, the API login request with `username` and `password` returns an error. You can switch to token-based authentication with `secret_key` or contact ThoughtSpot Support for assistance.\n\nThe token obtained from ThoughtSpot is valid for 5 minutes by default. You can configure the token expiration time as required.\n\n#### Just-in-time provisioning\n\nFor [just-in-time user creation and provisioning](https://developers.thoughtspot.com/docs/just-in-time-provisioning), specify the following attributes in the API request:\n\n* `auto_create`\n* `username`\n* `display_name`\n* `email`\n* `group_identifiers`\n\nSet `auto_create` to `true` if the username does not exist in ThoughtSpot. If the user already exists in ThoughtSpot and `auto_create` is set to `true`, user properties such as display name, email and group assignment will be updated.\n\nTo add a new user and assign privileges during auto-creation, the `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege is required. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled, the `CONTROL_TRUSTED_AUTH` (**Can Enable or Disable Trusted Authentication**) privilege is required.\n\n#### Important point to note\nAll options in the token creation APIs that define user access to data in ThoughtSpot will take effect during token creation, not when the token is used for authentication. For example, `auto_create:true` will create the user when the authentication token is created.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Authentication
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetFullAccessTokenRequest'
required: true
parameters: []
responses:
'200':
description: Bearer auth token creation successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
examples:
example_1:
description: Full-access token generated using cluster secret key
value:
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_full_token.signature
creation_time_in_millis: 1724277430000
expiration_time_in_millis: 1724277730000
scope:
access_type: FULL
org_id: 0
valid_for_user_id: 59481331-ee53-42be-a548-bd87be6ddd4a
valid_for_username: tsadmin
example_2:
description: Full-access token for a JIT-provisioned user in a specific org
value:
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_jit_full_token.signature
creation_time_in_millis: 1724278000000
expiration_time_in_millis: 1724278300000
scope:
access_type: FULL
org_id: 1
valid_for_user_id: b3d9e1f7-2a4c-4e8b-9d1f-6c5a3b8e7d2f
valid_for_username: jit_analyst@example.com
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_request:
summary: Invalid request
value:
error:
message:
code: 10002
incident_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
trace_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
debug: Either secret_key or password must be provided.
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized_access:
summary: Unauthorized access
value:
error:
message:
code: 10097
incident_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
trace_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
debug: Invalid credentials. The provided secret key or password is incorrect.
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
forbidden_access:
summary: Forbidden access
value:
error:
message:
code: 10023
incident_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
trace_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
debug: Trusted authentication is not enabled for this cluster or org.
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error
value:
error:
message:
code: 10038
incident_id_guid: d4e5f678-9012-3456-defa-456789012345
trace_id_guid: d4e5f678-9012-3456-defa-456789012345
debug: Unexpected server error while generating the full-access token.
security: []
/api/rest/2.0/auth/token/object:
post:
operationId: getObjectAccessToken
description: "\n <span class=\"since-beta-tag\">Version: 9.0.0.cl or later</span>\n\nGenerates an authentication token that provides access to a specific metadata object. This object list is intersected with the list of objects the user is allowed to access via group membership. For more information, see [Object security](https://docs.thoughtspot.com/cloud/latest/security-data-object#object_security).\n\n#### Usage guidelines\n\nYou can generate a token for a user by providing a `username` and `password`, or by using the `secret_key` generated for your instance. To generate a `secret_key`, the administrator must enable [Trusted authentication](https://developers.thoughtspot.com/docs/trusted-auth-secret-key) in the **Develop** > **Customizations** > **Security Settings** page.\n\n**Note**:\n* When both `password` and `secret_key` are included in the API request, `password` takes precedence.\n* If [Multi-Factor Authentication (MFA)](https://docs.thoughtspot.com/cloud/latest/authentication-local-mfa) is enabled on your instance, the API login request with `username` and `password` returns an error. You can switch to token-based authentication with `secret_key` or contact ThoughtSpot Support for assistance.\n\nThe token obtained from ThoughtSpot is valid for 5 minutes by default. You can configure the token expiration time as required.\n\n#### Just-in-time provisioning\n\nFor [just-in-time user creation and provisioning](https://developers.thoughtspot.com/docs/just-in-time-provisioning), specify the following attributes in the API request:\n\n* `auto_create`\n* `username`\n* `display_name`\n* `email`\n* `group_identifiers`\n\nSet `auto_create` to `true` if the user is not available in ThoughtSpot. If the user already exists in ThoughtSpot and the `auto_create` parameter is set to `true`, user properties such as display name, email, and group assignment will be updated.\n\nTo add a new user and assign privileges, the `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege is required. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled, the `CONTROL_TRUSTED_AUTH`(**Can Enable or Disable Trusted Authentication**) privilege is required.\n\n#### Important point to note\n\nAll options in the token creation APIs that define user access to data in ThoughtSpot will take effect during token creation, not when the token is used for authentication. For example, `auto_create:true` will create the user when the aut
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thoughtspot/refs/heads/main/openapi/thoughtspot-authentication-api-openapi.yml