Session APIs

The Session APIs allow ThoughtSpot users to authenticate and manage their sessions.

POST /tspublic/v1/session/login
Signs in a user to ThoughtSpot system.

POST /tspublic/v1/session/auth/token
Generates an authentication token for a user session.

GET /tspublic/v1/session/login/token
Creates a login session for authenticated users when trusted authentication is enabled.

This request method sends authentication attributes as query string parameters in the request URL.

POST /tspublic/v1/session/login/token
Authenticates and logs in a user to ThoughtSpot.

This request method sends authentication attributes in the request body as formData parameters. For a secure exchange of authentication information, ThoughtSpot recommends using the POST request method.

POST /tspublic/v1/session/logout
Logs out a user from an existing session.

POST /tspublic/v1/session/homepinboard
Sets a specific pinboard as a home pinboard.

GET /tspublic/v1/session/homepinboard
Returns the GUID of the pinboard that is set as a home pinboard for the current logged-in user.

DELETE /tspublic/v1/session/homepinboard
Removes the home pinboard settings for the current logged-in user.

POST /tspublic/v1/session/info
Gets session information.

Sign in as a ThoughtSpot user

You can programmatically sign in to ThoughtSpot using the /tspublic/v1/session/login API endpoint.

Resource URL

POST /tspublic/v1/session/login

Request Parameters

Form parameter Description

username

String. Username of the user account.

password

String.The password of the user account.

rememberme

Boolean. A flag to remember the user session. When set to true, a session cookie that persists in subsequent API calls is set. The system default is false.

Example requests

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'username=test&password=fhfh2323bbn&rememberme=false' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/login'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/login

Response codes

HTTP status code Description

200

User logged in

204

Successful login

401

Login failure/unauthorized request

Log out of a user session

To log out of your current session programmatically, use the /tspublic/v1/session/logout API endpoint.

Resource URL

POST /tspublic/v1/session/logout

Example request

cURL
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/logout'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/logout

If the logout request is sent as an AJAX call, add the following parameter to send credentials with the request:

xhrFields: { withCredentials: true }

Response codes

HTTP status code Description

200

User logged out

204

Successful log out of user

401

Logout failure/unauthorized request

Obtain an authentication token

ThoughtSpot supports the trusted authentication method, which is also known as token-based authentication. In the trusted authentication method, ThoughtSpot users are authenticated by an external authentication server. When ThoughtSpot receives a request from a trusted authentication service, it returns an authentication token to allow authenticated users to access ThoughtSpot content. If you have enabled trusted authentication on ThoughtSpot and obtained a secret key, you can use the /tspublic/v1/session/auth/token API to get an authentication token for a ThoughtSpot user.

Resource URL

POST /tspublic/v1/session/auth/token

Request parameters

Form parameter Description

secret_key

String. The secret key string provided by the ThoughtSpot application server. ThoughtSpot generates this secret key when you enable trusted authentication.

username

String. The username of the user configured in ThoughtSpot.

access_level

String. User access privilege. Valid values are:

  • FULL - Creates a session with full access.

  • REPORT_BOOK_VIEW - Allows view access to the specified visualizations.

id

string

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/auth/token'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/auth/token

Example response

The API returns an authentication token for the user:

JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCRPMFA2S0ZlNm51Qlo4NFBlZUppdzZ3PT0kMnJKaSswSHN6Yy96ZGxqdXUwd1dXZkovNVlHUW40d3FLMVdBT3hYVVgxaz0

Response codes

HTTP status code Description

200

The authentication token is generated successfully.

401

Unauthorized request or invalid token.

500

Token-based trusted authentication is not enabled on ThoughtSpot.

Authenticate and log in a user

To authenticate and log in a user, you must obtain a login token from the ThoughtSpot system. After you receive the login token, you can send the authentication attributes to the /tspublic/v1/session/login/token endpoint using a POST or GET request.

  • GET /tspublic/v1/session/login/token

    This request method sends the user authentication attributes as query string parameters in the request URL.

  • POST /tspublic/v1/session/login/token

    This request method sends the user authentication attributes as formData parameters in the request body of the API call. For secure exchange of authentication information, we recommend using the `POST`request method.

Resource URLs

GET /tspublic/v1/session/login/token
POST /tspublic/v1/session/login/token

Request parameters

Query parameter Description

username

String. The username of the user who requested access to ThoughtSpot.

auth_token

String.The login token obtained from ThoughtSpot.

redirect_url

String.The URL to which you want to redirect the user after a successful login. This URL is fully encoded and includes the authentication token obtained for the user.

https://<redirect-domain>/?authtoken=<user_auth_token>&embedApp=true&primaryNavHidden=true#/embed/viz/<pinboard_id>/<viz-id>

For example, if the user has requested access to a specific visualization on a pinboard, the redirect URL includes the host domain to which the user will be redirected, the authentication token, and the visualization and pinboard IDs.

Example request

cURL
curl -X GET \
--header 'Accept: text/html' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/login/token?username=tsuser&auth_token=JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCRPMFA2S0ZlNm51Qlo4NFBlZUppdzZ3PT0kMnJKaSswSHN6Yy96ZGxqdXUwd1dXZkovNVlHUW40d3FLMVdBT3hYVVgxaz0&redirect_url=https://<ThoughtSpot-Host>/?embedV2=true#/pinboard/7a9a6715-e154-431b-baaf-7b58246c13dd%2F'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/login/token?username=tsadmin&auth_token=JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCRPMFA2S0ZlNm51Qlo4NFBlZUppdzZ3PT0kMnJKaSswSHN6Yy96ZGxqdXUwd1dXZkovNVlHUW40d3FLMVdBT3hYVVgxaz0&redirect_url=https://<ThoughtSpot-Host>/?embedV2=true#/pinboard/7a9a6715-e154-431b-baaf-7b58246c13dd%2F

The following example shows a POST request with authentication attributes in the request body:

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: text/html' \
--header 'X-Requested-By: ThoughtSpot' \
-d  'username=tsadmin&auth_token=JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCREMUlCcWV5VVJMb2lZaFpnTUhjMHVnPT0kZklpQVFGTFp0RU5QTFFwcGxOUmF5WWU4ZGtGU1d6THdlUDBEOUY4WkhSWT0&redirect_url=https://<ThoughtSpot-Host>/?embedV2=true#/pinboard/7a9a6715-e154-431b-baaf-7b58246c13dd%2F'
'https://<ThoughtSpot-Host>/callosum/v1/tspublic/v1/session/login/token'
Request URL
https://<ThoughtSpot-Host>/callosum/v1/tspublic/v1/session/login/token

Example response

On successful login, the API returns the application details. The following example shows a partial output.

<!doctype html>
<html lang="en">
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width">
    <meta charset="utf-8">
    <meta name="description" content="">
        <!-- Preloading Fonts -->
        <link rel="preload" href="node_modules/@thoughtspot/radiant/widgets/resources/font/optimo/Plain-Light.otf"
              as="font" crossorigin>
        <link rel="preload" href="node_modules/@thoughtspot/radiant/widgets/resources/font/bb-roller/BB-Roller-Mono-Regular-fontlab.ttf"
              as="font" crossorigin>
        <link rel="preload" href="node_modules/@thoughtspot/radiant/widgets/resources/font/optimo/Plain-Regular.otf"
              as="font" crossorigin>
        <link rel="preload" href="node_modules/@thoughtspot/radiant/widgets/resources/font/optimo/Plain-Medium.ttf"
              as="font" crossorigin>
        <link rel="preload" href="node_modules/@thoughtspot/radiant/widgets/resources/font/optimo/Plain-LightIta.otf"
              as="font" crossorigin>
        <link rel="modulepreload" href="https://cdn.skypack.dev/react">
	<link rel="modulepreload" href="https://cdn.skypack.dev/react-dom">
    <link rel="stylesheet" href='(none)'>
    <style>
        .bk-app-loading-indicator {
    position: absolute;
    height: 100%;
    width: 100%;
    display: -webkit-box;
    display: -moz-box;
    display: -ms-flexbox;
    display: -webkit-flex;
    display: flex;
    flex-direction: row;
    -ms-flex-direction: row;
    -webkit-flex-direction: row;
    align-items: stretch;
    -webkit-align-items: stretch;
    -ms-flex-align: stretch;
    max-width: 100%;
    box-sizing: border-box;
}
    </style>
</head>
<body>
    <div class="bk-app-loading-indicator">
        <div class="load-wrap">
    <div>
        <div class="circle"></div>
        <div class="circle"></div>
        <div class="circle"></div>
    </div>
</div>
    </div>

    <script type="text/javascript" id="app-init">
        // Top level namespace var declaration
        var blink = {};
        // Object to store all CDN related variables
        blink.cdnAutoUpdateConfig = {};
        // Location of Eureka Base URL
        blink.eurekaBasePath = 'https://d2if2nytu6z4ml.cloudfront.net';
        // Keys set in blink.env will override / create flags
        blink.env = {
            dev: false
        };
        blink.commitId = '600e99e3c3ebe1b4d89abd99e920c6939616f54c';
        blink.gitBranch = '(HEAD detached at 600e99e3c3e)';
        blink.buildTimeStamp = 'Thu May 20 2021 09:25:58';
        blink.depsPath = 'node_modules';
        blink.localeSuffix = '.' + blink.commitId;
        blink.metrics = {
            scriptsLoadStartTime: window.performance.now()
        };

        function createNode(tag, attributes) {
            var node = document.createElement(tag);
            Object.keys(attributes).forEach(function (key) {
                return node[key] = attributes[key];
            });
            return node;
        }
        function appendNodesToDom(nodes) {
            var fragment = document.createDocumentFragment();
            nodes.forEach(function (node) {
                return fragment.appendChild(node);
            });
            document.getElementsByTagName('body')[0].appendChild(fragment);
        }
        function fetchAndLoadRelease(rcLink) {
            fetch(rcLink).then(function (response) {
                return response.json()
            }).then(function (releaseJson) {
                blink.cdnAutoUpdateConfig.evaluationMode = true;
                blink.cdnAutoUpdateConfig.currentReleaseVersion = releaseJson.releaseVersion;
                blink.cdnAutoUpdateConfig.cdnBuildTimestamp = releaseJson.buildTimestamp;
                blink.cdnAutoUpdateConfig.cdnBasePath = releaseJson.basePath;
                var nodes = releaseJson.resources.css.map(function (cssScript) {
                    return createNode('link', {
                        type: 'text/css',
                        rel:'stylesheet',
                        href: [blink.cdnAutoUpdateConfig.cdnBasePath, cssScript].join('/')
                    })
                });

                nodes = nodes.concat(releaseJson.resources.js.map(function (script) {
                    return createNode('script', {
                        src: [blink.cdnAutoUpdateConfig.cdnBasePath, script].join('/'),
                        async: false
                    });
                }));
                nodes = nodes
                    .concat(releaseJson.resources.modules.map(function (module, index) {
                        return createNode('script', {
                            async: false,
                            type: 'module',
                            src: [blink.cdnAutoUpdateConfig.cdnBasePath, module].join('/'),
                            id: 'module-script' + index
                        });
                    }));
                nodes = nodes
                    .concat(releaseJson.resources.noModule.map(function (noModule, index) {
                        return createNode('script', {
                            async: false,
                            noModule: true,
                            src: [blink.cdnAutoUpdateConfig.cdnBasePath, noModule].join('/'),
                            id: 'nomodule-script' + index
                        });
                    }));
                appendNodesToDom(nodes);
            }, function (error) {
                appendNodesToDom([createNode('div', {
                    innerText: 'unable to fetch: ' + rcLink +
                    'Link does not exist'
                })]);
            });
        }
        var ua = window.navigator && window.navigator.userAgent;
        var trident = ua && ua.indexOf('Trident/');
        var edge = ua && ua.indexOf('Edge');
        var safari = ua && ua.indexOf('Safari');
        var chrome = ua && ua.indexOf('Chrome');

    </script>

        <link type="text/css" rel="stylesheet" href="resources/css/all.min.90630a0a141abec0.css">

        <script src="js/lib.min.bcef417e2b193abd.js"></script>
        <script src="js/templates.133e974a290769f7.js"></script>
        <script src="js/all.min.b4be265ed3041f65.js"></script>
        <script type="module" src="js/module/app-ad896427.js
" id="module-script"></script>
        <script nomodule src="js/nomodule/app.js" id="nomodule-script"></script>
    <app-controller class="bk-app-controller-container"></app-controller>
</body>
</html>

Response codes

HTTP status code Description

200

The user is logged in successfully.

302

The user is redirected to the specified URL.

401

Unauthorized request or invalid token.

Get session information

To get the session information for the current logged-in user on a given ThoughtSpot cluster, send a GET request to the /tspublic/v1/session/info endpoint.

Resource URL

GET /tspublic/v1/session/info

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/info'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/info

Example response

If the operation is successful, the API returns a response with the session information and the current configuration of the cluster.

{
  "userName": "tsuser1",
  "userDisplayName": "Administrator",
  "userEmail": "tsuser1@thoughtspot.com",
  "userCreatedTime": 1354006445722,
  "userExpirationTime": 1634345144438,
  "userGUID": "59481331-ee53-42be-a548-bd87be6ddd4a",
  "apiVersion": "v1",
  "canChangePassword": true,
  "isSystemUser": false,
  "logicalModelVersion": 401,
  "userGroupMask": 6,
  "privileges": [
    "ADMINISTRATION",
    "USERDATAUPLOADING",
    "DATADOWNLOADING",
    "DATAMANAGEMENT",
    "SHAREWITHALL",
    "A3ANALYSIS"
  ],
  "expirationTime": 1632154574,
  "authToken": "gv4HjljdCZKbN4LMEHNn0p7ct12/4KSaCwKDfu/UVnA=",
  "locale": "en_GB",
  "timezone": "UTC",
  "dateFormat": {
    "formatPattern": "dd/MM/yyyy"
  },
  "timeFormat": {
    "formatPattern": "HH:mm:ss"
  },
  "dateTimeFormat": {
    "formatPattern": "dd/MM/yyyy HH:mm"
  },
  "integerFormat": {},
  "decimalFormat": {},
  "clientState": {
    "preferences": {
      "HOMEPAGE_EUREKA": true,
      "PANEL_STATE": "EXPANDED",
      "sageDataSource": [
        "8eaf2704-9754-4c48-830d-27e5317b2c64",
        "b0248372-5e68-4815-8682-67715456efb2"
      ],
      "OPEN_ANSWER_EDIT_PANEL": "VIZ_EDITOR"
    },
    "tips": {
      "chartConfigChipTip": true
    }
  },
  "configInfo": {
    "highCardinalityMaxDataSize": 20000,
    "fetchPivotSummaryFromBackend": true,
    "vizRenderingQueueTimeoutMS": 30000,
    "enableColumnSummariesByDefault": true,
    "isAnswerV2OnByDefault": false,
    "defaultChartDataSize": 5000,
    "maxFilterValues": 10000,
    "useDomainQualifiedName": true,
    "enableInstantSearch": false,
    "defaultFilterNonCascading": false,
    "pinboardFilterConfiguratorDisabled": false,
    "isAnswerUndoStackEnabled": false,
    "answerV2Experience": true,
    "enablePinboardV2": false,
    "enableCJA": false,
    "blinkHelpConfigList": [
      {
        "enabled": true,
        "title": "Keywords",
        "id": "BLINK_KEYWORDS",
        "url": "https://cloud-docs.thoughtspot.com/{versionNameForLink}/reference/keywords.html",
        "iconFilePath": ""
      },
      {
        "enabled": true,
        "title": "Release notes",
        "id": "BLINK_RELEASE_NOTES",
        "url": "https://cloud-docs.thoughtspot.com/{versionNameForLink}/release/notes.html",
        "iconFilePath": ""
      },
      {
        "enabled": true,
        "title": "Documentation",
        "id": "BLINK_DOCUMENTATION",
        "url": "https://cloud-docs.thoughtspot.com/{versionNameForLink}",
        "iconFilePath": ""
      }
    ],
    "blinkActionConfigList": [],
    "embedActionConfigList": [
      {
        "id": "598450a5-c402-4dcb-a127-8797bcda378f",
        "name": "view report",
        "version": "v2",
        "type": "CALLBACK",
        "detail": {
          "link": "",
          "function": "view-report",
          "authSelect": "NONE",
          "authToken": "",
          "encodeUser": "",
          "apiKey": "X-API-KEY",
          "apiValue": "",
          "additionalUrlHeaders": "{}"
        },
        "actionAssociationMap": {
          "ANSWER": {
            "087f51a0-f352-4497-b39a-e69ea8b4d5a1": {
              "enabled": "true",
              "context": "NONE"
            }
          }
        },
        "context": "NONE",
        "availability": [
          "GLOBAL"
        ]
       },
}

Response codes

HTTP status code Description

200

Successful operation.

Set a pinboard as a home pinboard

To set a pinboard as a home pinboard for a user account, send a POST request to the /tspublic/v1/session/homepinboard API endpoint. If a home pinboard is configured for a user account, ThoughtSpot displays it as the default home page when the user logs in.

Resource URL

POST /tspublic/v1/session/homepinboard

Request parameters

Form parameter Description

id

String. GUID of the pinboard to be set as a home pinboard.

userid
Optional

String. GUID of the user account for which you want to set the home pinboard. If the userid attribute is not defined, ThoughtSpot sets the home pinboard of the current logged-in user.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'id=7a9a6715-e154-431b-baaf-7b58246c13dd&userid=59481331-ee53-42be-a548-bd87be6ddd4a' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/homepinboard'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/homepinboard

Response codes

HTTP status code Description

204

The specified pinboard is set as a home pinboard.

403

The pinboard with the given ID is not accessible.

401

Unauthorized request or invalid token.

404

The specified pinboard was not found.

Get details of the home pinboard

To get the GUID of pinboard that is currently set as a home pinboard, send a GET request to the /tspublic/v1/session/homepinboard API endpoint.

Resource URL

GET /tspublic/v1/session/homepinboard

Example request

cURL
curl -X GET \
--header 'Accept: text/plain' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/homepinboard'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/homepinboard

Example response

If the home pinboard is set in the current logged-in user’s account, the API returns the GUID of the pinboard set as a home pinboard:

7a9a6715-e154-431b-baaf-7b58246c13dd

Response codes

HTTP status code Description

200

Successful operation.

Remove a home pinboard

To remove the home pinboard setting from current logged-in user’s account, send a DELETE request to the /tspublic/v1/session/homepinboard API endpoint.

Resource URL

DELETE /tspublic/v1/session/homepinboard

Example request

cURL
curl -X DELETE \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/homepinboard'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/session/homepinboard

Example response

If the home pinboard is set in the current logged-in user’s account, the API returns the following response:

Response Code
200

Response codes

HTTP status code Description

200

Successful operation