LLMs.txt: Complete documentation index for AI agents
REST API v2.0 authentication
Cloud
26.10.0.clCloud (Latest)
26.9.0.clCloud
26.8.0.clCloud
Software
26.3.0.swSoftware (Latest)
10.10.0.swSoftware
10.1.0.swSoftware
GitHub

REST API v2.0 authentication

To create, access, and modify ThoughtSpot objects and resources through the REST API v2 endpoints, you need to authenticate to ThoughtSpot and authorize your API requests.

Overview🔗

The ThoughtSpot REST API v2 framework supports the following types of authentication:

TypePurpose

Token-based authentication

REST clients can obtain an authentication token from ThoughtSpot using any REST API v2 token generation endpoint and use this token in their subsequent API calls to authorize their API requests.

ThoughtSpot’s REST API v2 token endpoints allow REST clients to generate tokens for specific use cases. These endpoints allow generating a token for a given user by specifying the username and password or secret_key in the generation request. For trusted authentication and custom tokens for ABAC, use the username and secret_key parameters in API requests.

For more information, see Token-based authentication.

Basic authentication/Cookie-based authentication

In this method, a REST client sends an API request to the api/rest/2.0/auth/session/login endpoint with the username and password. A successful login returns a session cookie from ThoughtSpot, which can be included in subsequent REST API calls.

Note

If multifactor authentication (MFA) is enabled on your ThoughtSpot instance, API requests with username and password parameters to the login and authentication endpoints will return an error.

This issue occurs because when MFA is enabled, users must provide the additional authentication factor to log in to ThoughtSpot. Currently, there is no mechanism to pass the second factor via the standard API login endpoint, therefore the API request will not be successful.

If your implementation uses basic authentication with the login endpoint, ThoughtSpot recommends switching to the token-based authentication method. For further guidance, contact ThoughtSpot Support.

Token-based authentication🔗

ThoughtSpot provides different REST API endpoints for developers and administrators to issue authentication tokens to end users. Each endpoint helps developers achieve slightly different use cases:

Token typePurpose and API endpoint

Full access token

API endpoint: POST /api/rest/2.0/auth/token/full

Use case: Authenticates users with standard row-level security (RLS) rules and object permissions, administered through user properties and group memberships.

Example: Authenticate a user via Trusted Auth, without any particular need for RLS.

Custom access token

Use case: Assigns variable values to users when authenticating them, enabling ABAC via RLS rules when logging users into ThoughtSpot.

API endpoint:`POST /api/rest/2.0/auth/token/custom`

Example: Authenticate a user, and define RLS values on tables such that the user can only access data for specific regions in ThoughtSpot when logged in using the token.

Object access token

Use case: Assigns a subset of objects to a user for a given session. This object list is intersected with the list of the objects that the user has been permitted to view or edit via group membership.

API endpoint: POST /api/rest/2.0/auth/token/object

Example: Authenticate a user who usually can see Liveboards A, B, and C, but for the context of that session, solely give access to Liveboard “A”.

Recommendations🔗

  • ThoughtSpot recommends using a full access token for users, unless there is a need to set up ABAC via RLS, in which case a custom token is required.

  • For centralized control of object access and to restrict user access to specific objects, ThoughtSpot recommends using the Object security method.

Data security considerations🔗

ThoughtSpot also allows developers to pass context or update the experience of an end user via the Visual Embed SDK. Updating the context of the embedded object is not data security.

For example, a developer may choose to restrict data access for a user so they only see data for country="United States". To implement this, use the RLS feature. If required, values passed for RLS can be updated via a custom access token. However, this user may need to be shown data for state = California, or product category = jeans in ThoughtSpot, so the analysis conducted in ThoughtSpot matches the context of the host application. To accommodate this use case, developers can update the Liveboard filters, runtime filters, or parameters via the Visual Embed SDK. For more information, see Filters overview.

A clear distinction must be made between RLS and context update via HostEvents, runtime filters, and parameter updates.

RLS and ABAC via RLS through a custom access tokenProgrammatically set Liveboard filter, runtime filter, or parameter values

Security feature

✅

❌
These filtering mechanisms are not secure.

Appropriate for context updates

❌
Once the security rules are set, they are fixed for at least that user’s session. As a result, this approach is not suited to quickly updating a user’s context throughout a session.

✅

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 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🔗

ParameterDescription

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
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🔗

ParameterDescription

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

String. Name or ID of the Org for which to enable or disable trusted authentication. Specify this attribute within the org_preferences array.

API request🔗

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.

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 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.

Note

  • When both password and secret_key are included in the API request, password takes precedence.

  • If Multi-Factor Authentication (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.

API request with username and password🔗

To get an access token that grants full access to ThoughtSpot, send a POST request with username, password, and other attributes to the /api/rest/2.0/auth/token/full endpoint:

ParameterDescription

username

String. Username of the ThoughtSpot user.

password

String. Password of the user account.

org_id
Optional

Integer. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0).

validity_time_in_sec
Optional

Integer. Token validity duration in seconds. By default, the token is valid for 5 minutes. 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.

Example request
cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full' \
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "password": "Guest123!",
  "org_id": 1,
  "validity_time_in_sec": 86400
}'
Example response

If the API request is successful, ThoughtSpot returns the authentication token that grants full application access.

{
  "token": "{AUTH_TOKEN}",
  "creation_time_in_millis": 1675129264089,
  "expiration_time_in_millis": 1675129564089,
  "scope": {
    "access_type": "FULL",
    "org_id": 1,
    "metadata_id": null
  },
  "valid_for_user_id": "59a122dc0-38d7-43e7-bb90-86f724c7b602",
  "valid_for_username": "tsUserA"
}

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 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:

ParameterDescription

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 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
Optional

Integer. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0).

Example request

The following example shows the request body with username and secret_key:

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}api/rest/2.0/auth/token/full'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "org_id": 1,
  "validity_time_in_sec": 300,
  "auto_create": false,
  "secret_key": "2657f6f9-6aa9-4432-99f2-bf0d70f240ac"
}'
Example response

If the API request is successful, ThoughtSpot returns the authentication token that grants full application access.

{
   "token":"{AUTH_TOKEN}",
   "creation_time_in_millis":1675163671270,
   "expiration_time_in_millis":1675163971270,
   "scope":{
      "access_type":"FULL",
      "org_id":1,
      "metadata_id":null
   },
   "valid_for_user_id":"fd873d1e-11cc-4246-8ee2-78e78d2b5840",
   "valid_for_username":"tsUserA"
}

The token issued by ThoughtSpot can be used to log in a user. Note that the token is necessary only during the login process, after which any request to ThoughtSpot includes session cookies identifying the signed-in user.

Generating a custom token for ABAC implementation🔗

To get a token with security entitlements encoded in JSON Web Token (JWT) format for a user, use the /api/rest/2.0/auth/token/custom API endpoint. This API allows administrators to generate a token with specific attributes, such as variable values for the formula variables referenced in row-level security (RLS) rules, and thus allows ThoughtSpot administrators and developers to implement Attribute-Based Access Control (ABAC) via RLS.

For more information about the API requests and ABAC implementation, see Attribute-Based Access Control (ABAC) via RLS.

Generating an object access token🔗

The object access token grants read-only access to a specific ThoughtSpot metadata object, as defined by the object_id property in the request. This token can be used to authorize API requests that need access only to that particular object, not the full application. To obtain a token that grants read-only access to a ThoughtSpot metadata object, use the /api/rest/2.0/auth/token/object endpoint.

API request with username and password🔗

To get a token that grants read-only access to a ThoughtSpot metadata object, send a POST request with username, password, object_id, and other attributes to the /api/rest/2.0/auth/token/object endpoint:

ParameterDescription

username

String. Username of the ThoughtSpot user.

password

String. Password of the user account.

object_id

String. GUID of the ThoughtSpot object. The token obtained from this API request grants read-only access to the specified object.

org_id
Optional

Integer. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0).

validity_time_in_sec
Optional

Integer. Token validity duration in seconds. By default, the token is valid for 5 minutes.

Example request
cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object' \
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "org_id": 1,
  "password": "Guest123!",
  "object_id": "fa68ae91-7588-4136-bacd-d71fb12dda69"
}'
Example response

If the API request is successful, ThoughtSpot returns the authentication token that grants access to the metadata object specified in the request.

{
  "token": "{AUTH_TOKEN}",
  "creation_time_in_millis": 1675129264089,
  "expiration_time_in_millis": 1675129564089,
  "scope": {
    "access_type": "REPORT_BOOK_VIEW",
    "org_id": 1,
    "metadata_id": "e65d7d3b-c934-4a59-baa1-d5cb7b679cc9"
  },
  "valid_for_user_id": "59a122dc0-38d7-43e7-bb90-86f724c7b602",
  "valid_for_username": "tsUserA"
}

API request with username and secret key🔗

To get a token that grants read-only access to a specific metadata object, send a POST request with username, secret_key, object_id, and other attributes to the /api/rest/2.0/auth/token/object endpoint:

ParameterDescription

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 when trusted authentication is enabled on your instance.

object_id

String. GUID of the ThoughtSpot object. The token obtained from this API request grants read-only access to the specified object.

org_id
Optional

Integer. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0).

validity_time_in_sec
Optional

Integer. Token expiry duration in seconds. The default duration is 300 seconds.

Example request

The following example shows the request body with username, secret_key, and object_id:

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "org_id": 1,
  "object_id": "061457a2-27bc-43a9-9754-0cd873691bf0",
  "secret_key": "69fb6d98-1696-42c0-9841-22b078c04060"
}'
Example response

If the API request is successful, ThoughtSpot returns the authentication token that grants access to the metadata object specified in the request.

{
   "token":"{AUTH_TOKEN}",
   "creation_time_in_millis":1675162190374,
   "expiration_time_in_millis":1675162490374,
   "scope":{
      "access_type":"REPORT_BOOK_VIEW",
      "org_id":1,
      "metadata_id":"061457a2-27bc-43a9-9754-0cd873691bf0"
   },
   "valid_for_user_id":"fd873d1e-11cc-4246-8ee2-78e78d2b5840",
   "valid_for_username":"tsUserA"
}

Just-in-time provisioning of users🔗

If you are generating an authentication token for a new user in ThoughtSpot, you can use the auto_create option to provision a user and obtain a token for that user. Creating a new user requires request attributes such as a username, email address, display name, groups, and Org details.

Users created via JIT provisioning are identical to users created in the UI or via the user creation API, except they do not have passwords in ThoughtSpot, and they cannot access ThoughtSpot other than through an SSO method. You can assign a password to any user later through the UI or a REST API call.

The following REST API v2 endpoints support just-in-time (JIT) provisioning:

  • POST /api/rest/2.0/auth/token/full

  • POST /api/rest/2.0/auth/token/object

  • POST /api/rest/2.0/auth/token/custom

When auto_create is set to true in the API request, these endpoints allow you to create a user at the time of authentication if the user does not already exist. When provisioning a new user, ensure that you include display_name, email, and group details in the API request.

Example requests🔗

The following sample shows the request format to provision a new user just-in-time via the /api/rest/2.0/auth/token/full API endpoint and generate a full access token:

If the username already exists in ThoughtSpot, setting auto_create to true does not create a new user. Instead, it updates user properties such as display name, email, and group entitlements.

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full' \
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "secret_key": "69fb6d98-1696-42c0-9841-22b078c04060",
  "org_id": 2,
  "email": "userA@example.com",
  "display_name": "User A",
  "auto_create": true,
  "group_identifiers": [
    "DataAdmin",
    "Analyst"
  ]
}'

The following sample shows the request format to provision a new user just-in-time via the /api/rest/2.0/auth/token/object API endpoint and get an authentication token that grants access to a specific metadata object in ThoughtSpot:

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object' \
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "object_id": "061457a2-27bc-43a9-9754-0cd873691bf0",
  "secret_key": "69fb6d98-1696-42c0-9841-22b078c04060",
  "org_id": 2,
  "auto_create": true,
  "group_identifiers": [
    "DataAdmin",
    "Analyst"
  ]
}'

The following sample shows the request format to provision a new user just-in-time via the /api/rest/2.0/auth/token/custom API endpoint and generate a token with ABAC via RLS variable values.

If the username already exists in ThoughtSpot, setting auto_create to true does not create a new user. In this case, user properties such as display name, email, Org, and group entitlements are not updated.

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "UserA",
  "validity_time_in_sec": 300,
  "persist_option": "APPEND",
  "auto_create": true,
  "secret_key": "f8aa445b-5ff1-4a35-a58f-e324133320d5",
  "variable_values": [
    {
      "name": "country_var",
      "values": [
        "Japan",
        "Singapore",
        "Australia"
      ]
    },
    {
      "name": "department_var",
      "values": [
        "Sales",
        "Marketing"
      ]
    },
    {
      "name": "product_var",
      "values": [
        "TS_WILDCARD_ALL"
      ]
    }
  ],
  "objects": [
    {
      "type": "LOGICAL_TABLE",
      "identifier": "35aa85fe-fbb4-4862-a335-f69679ebb6e0"
    }
  ]
}'
Note

If auto_create is set to true and the username specified in the API request already exists in ThoughtSpot, the /api/rest/2.0/auth/token/custom API does not update user properties such as display name, email, Org, or group assignments.

Multi-Org tokens Beta🔗

By default, a token authorizes API requests in a single Org. From 26.10.0.cl, ThoughtSpot users with cluster administration privileges can request a token authorized for multiple Orgs by including the optional scope object in the token request, and then select the Org for each request using the X-Org-Selector header.

Note

  • This feature is in Beta and is disabled by default. To enable this feature, contact ThoughtSpot Support.

  • Only users with cluster administration privileges can generate a multi-Org token.

Supported endpoints🔗

The scope request property is supported on the following token endpoints:

  • POST /api/rest/2.0/auth/token/full

  • POST /api/rest/2.0/auth/token/custom (supports SPECIFIC_ORGS only)

  • POST /api/rest/2.0/auth/token/object

The scope request property🔗

ParameterDescription

scope

Object. Optional. The set of Orgs the token is authorized to operate in, recorded at issuance. Requires cluster administration privileges. Specify the following attributes:

  • org_scope
    String. Org scope type. Valid values:

    • SPECIFIC_ORGS: authorizes the token for the Orgs listed in org_identifiers.

    • ALL_MEMBER_ORGS: authorizes the token for all Orgs the user is a member of. Not supported for custom (ABAC) tokens.

  • org_identifiers
    Array of strings. ID or name of the Orgs the token is authorized for. Required when org_scope is SPECIFIC_ORGS; ignored when org_scope is ALL_MEMBER_ORGS.

Request example🔗

A multi-Org token request replaces org_id with the scope object. The issued token is authorized for every Org in the requested set, and each API request selects its target Org with the X-Org-Selector header.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsAdminUser",
  "secret_key": "{SECRET_KEY}",
  "validity_time_in_sec": 86400,
  "scope": {
    "org_scope": "SPECIFIC_ORGS",
    "org_identifiers": ["1", "2", "5"]
  }
}'
Note
 The scope object in a single-Org token response carries no org_scope or org_ids properties. API requests made with this token always execute in the Org the token was issued for; the X-Org-Selector header is not required.

Response properties🔗

When a multi-Org token is issued, the scope object in the response includes the following additional properties.

{
  "token": "{AUTH_TOKEN}",
  "creation_time_in_millis": 1675129264089,
  "expiration_time_in_millis": 1675129564089,
  "scope": {
    "access_type": "FULL",
    "org_id": 1,
    "metadata_id": null,
    "org_scope": "SPECIFIC_ORGS",
    "org_ids": [
      {
        "id": 1,
        "name": "Org-Finance"
      },
      {
        "id": 2,
        "name": "Org-Sales"
      },
      {
        "id": 5,
        "name": "Org-Marketing"
      }
    ]
  },
  "valid_for_user_id": "59a122dc0-38d7-43e7-bb90-86f724c7b602",
  "valid_for_username": "tsAdminUser"
}

The same properties appear in the POST /api/rest/2.0/auth/token/validate response, so API clients can inspect which Orgs an existing token is authorized for.

PropertyDescription

scope.org_scope

String. Org scope the token is authorized for: SPECIFIC_ORGS or ALL_MEMBER_ORGS. This property is absent for a legacy single-Org token.

scope.org_ids

Array. The Orgs the token is authorized for when org_scope is SPECIFIC_ORGS.

Per-request Org selection🔗

Each API request made with a multi-Org token selects one Org from the token’s authorized set using the X-Org-Selector request header:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/users/search'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  -H 'X-Org-Selector: 2' \
  --data-raw '{}'

The header selects an Org from the authority the token already holds; it does not grant access to any Org outside the token’s scope. Selecting an Org outside the authorized set fails the request.

Generating a session token🔗

To generate a new authentication token for an existing authenticated session, send a GET request to /api/rest/2.0/auth/session/token. This endpoint mints a fresh bearer token valid for 24 hours. It does not return the token currently held by the caller’s session, but issues a new token derived from the authenticated session context.

Note

Use this endpoint when your integration needs a new token without requiring the user to re-authenticate. If you need a token with a specific expiry or security scope, use the POST /api/rest/2.0/auth/token/full, POST /api/rest/2.0/auth/token/custom, or POST /api/rest/2.0/auth/token/object endpoints instead.

Example request🔗

cURL
curl -X GET \
  --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/session/token' \
  -H 'Accept: application/json'

Example response🔗

If the API request is successful, ThoughtSpot returns a new authentication token. The expiration_time_in_millis value reflects the 24-hour validity of the newly issued token from the time of the request.

{
   "token": "{AUTH_TOKEN}",
   "creation_time_in_millis": 1704471154477,
   "expiration_time_in_millis": 1704557554477,
   "valid_for_user_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
   "valid_for_username": "tsadmin"
}

Revoking a token🔗

To revoke a token, send a POST request with the following attributes to the /api/rest/2.0/auth/token/revoke endpoint.

Request parameters
ParameterDescription

user_identifier

String. GUID or name of the ThoughtSpot user.

token

String. Token issued for the user specified in user_identifier.

Example request
cURL
curl -X POST \
  --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/token/revoke' \
  -H 'Authorization: Bearer {AUTH_TOKEN}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_identifier": "tsUserA",
  "token": "{access_token_user}"
}'
Example response

If the API request is successful, the access token is revoked, and the current user session becomes invalid. Before making another API call, you must obtain a new token.

Cookie-based authentication🔗

For cookie-based authentication, make an API call to the /api/rest/2.0/auth/session/login endpoint with the username, password, and other attributes in the request body.

Request parameters🔗

ParameterDescription

username

String. Username of the ThoughtSpot user.

password

String. The password of the user account.

org_identifier

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

Boolean. A flag to remember the user session. When set to true, the session cookie persists in subsequent API calls for about 7 days.

If remember_me is set to false, the user session times out after three hours of inactivity. To get a cookie assigned to your user session, you need to log in to ThoughtSpot again.

API request🔗

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/session/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "password": "Guest@123!",
  "remember_me": true
}'
Request URL
POST {ThoughtSpot-Host}/api/rest/2.0/auth/session/login

API response🔗

If the login is successful, ThoughtSpot returns a 204 status code. A session cookie is assigned to the logged-in user and sent in the response header.

Set-Cookie: JSESSIONID=b9a5b821-fa91-49ea-99fc-12817a141e76; Path=/; HttpOnly
Set-Cookie: clientId=76d83461-1b8a-425a-9116-66c8d6f006bb; Path=/; Secure; HttpOnly

Cookie usage in subsequent API requests🔗

The session cookie is automatically set in the request header when you make your subsequent API calls via a web browser. Note that if you are using a web browser or Postman to make a REST API call, the session cookie obtained from the /api/rest/2.0/auth/session/login API call is automatically set. REST clients in a non-browser environment must include the session cookie in the request header as shown in the following example:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/search' \
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  -H 'Cookie: JSESSIONID=fc3424f9-d3f0-4a24-bd33-400fd826cac7; clientId=70cf1328-af97-40b2-9bd5-1c520e133963' \
  --data-raw '{
    "metadata": [
     {
      "type": "LIVEBOARD"
      }
    ]
  }'
Note

If you are accessing the REST API outside a web browser, create a long-lived session object in your code, and then call the login API using that session object. Make subsequent REST API calls with the same session object to send the cookie along with the other aspects of the particular REST API call.

Viewing session information🔗

To get details of the session object for the currently logged-in user, send a GET request to the /api/rest/2.0/auth/session/user endpoint.

API request🔗

cURL
curl -X GET \
  --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/session/user' \
  -H 'Authorization: Bearer {AUTH_TOKEN}'\
  -H 'Accept: application/json'

API response🔗

If the API request is successful, ThoughtSpot returns the following response:

{
   "id":"658a4b35-d021-4009-bf16-c66504dee6a4",
   "name":"tsUserZ",
   "display_name":"tsUserZ",
   "visibility":"SHARABLE",
   "author_id":"59481331-ee53-42be-a548-bd87be6ddd4a",
   "can_change_password":true,
   "complete_detail":true,
   "creation_time_in_millis":1675163378622,
   "current_org":{
      "id":0,
      "name":"Primary"
   },
   "deleted":false,
   "deprecated":false,
   "account_type":"REMOTE_USER",
   "account_status":"ACTIVE",
   "email":"testUser1@thoughtspot.com",
   "expiration_time_in_millis":1675171235,
   "external":false,
   "favorite_metadata":[

   ],
   "first_login_time_in_millis":1675170739789,
   "group_mask":4,
   "hidden":false,
   "home_liveboard":null,
   "incomplete_details":[

   ],
   "is_first_login":false,
   "modification_time_in_millis":1675170835628,
   "modifier_id":"59481331-ee53-42be-a548-bd87be6ddd4a",
   "notify_on_share":true,
   "onboarding_experience_completed":false,
   "orgs":[
      {
         "id":0,
         "name":"Primary"
      }
   ],
   "owner_id":"658a4b35-d021-4009-bf16-c66504dee6a4",
   "parent_type":"USER",
   "privileges":[
      "AUTHORING",
      "USERDATAUPLOADING",
      "DATADOWNLOADING",
      "DEVELOPER"
   ],
   "show_onboarding_experience":true,
   "super_user":false,
   "system_user":false,
   "tags":[

   ],
   "tenant_id":"982d6da9-9cd1-479e-b9a6-35aa05f9282a",
   "user_groups":[
      {
         "id":"0b531ff7-2a5e-45ee-a954-43fbd25c4c92",
         "name":"DATAMANAGEMENT"
      },
      {
         "id":"4fa3f1ca-337a-4fb3-9e7c-dc85da8e6b8e",
         "name":"A3ANALYSIS"
      },
      {
         "id":"ed7435bc-cab4-40c2-ab2e-87e517eb3640",
         "name":"Developer"
      },
      {
         "id":"1cf05016-988c-422a-aae6-bf0ac9f106b7",
         "name":"USERDATAUPLOADING"
      }
   ],
   "user_inherited_groups":[
      {
         "id":"ed7435bc-cab4-40c2-ab2e-87e517eb3640",
         "name":"Developer"
      },
      {
         "id":"1cf05016-988c-422a-aae6-bf0ac9f106b7",
         "name":"USERDATAUPLOADING"
      },
      {
         "id":"4fa3f1ca-337a-4fb3-9e7c-dc85da8e6b8e",
         "name":"A3ANALYSIS"
      },
      {
         "id":"0b531ff7-2a5e-45ee-a954-43fbd25c4c92",
         "name":"DATAMANAGEMENT"
      }
   ],
   "welcome_email_sent":false
}

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 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.

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.

API request🔗

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/session/logout'  \
  -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.

© 2026 ThoughtSpot Inc. All Rights Reserved.