Session APIs

Session APIs

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

Supported operations🔗

API endpointAvailable from

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

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 6.0.x

POST /tspublic/v1/session/auth/token
Generates an authentication token for a user session.
Use this API endpoint to obtain a token for trusted authentication.

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 7.1.1

GET /tspublic/v1/session/login/token (Deprecated)
Authenticates and logs in a user using a token obtained from the /tspublic/v1/session/auth/token API call.
This request method sends authentication attributes as query string parameters in the request URL.
This API call is not required if you are using Visual Embed SDK.

ThoughtSpot Cloud ts7.may.cl
ThoughtSpot Software 7.1.1

POST /tspublic/v1/session/login/token
Authenticates and logs in a user using a token obtained from the /tspublic/v1/session/auth/token API call.
This request method sends authentication attributes in the request body as formData parameters. For secure exchange of authentication information, we recommend using the POST request method.
This API call is not required if you are using Visual Embed SDK.

ThoughtSpot Cloud ts8.nov.cl
ThoughtSpot Software 7.2.1.sw

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

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 6.0.x

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

PUT /tspublic/v1/session/orgs
Allows switching between organizations on a multi-tenant instance.

ThoughtSpot Cloud 8.10.0.cl
ThoughtSpot Software Not available

GET /tspublic/v1/session/orgs
Gets Orgs for the logged-in user.

ThoughtSpot Cloud 8.10.0.cl
ThoughtSpot Software Not available

GET /tspublic/v1/session/orgs/users/{userid}
Gets Orgs for a specific user.

ThoughtSpot Cloud 8.10.0.cl
ThoughtSpot Software Not available

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

ThoughtSpot Cloud ts7.jun.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.jun.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.jun.cl
ThoughtSpot Software 7.1.1

Required permissions🔗

You require ThoughtSpot login credentials to create a session object and obtain a login token.

Sign in as a ThoughtSpot user (Basic authentication)🔗

In the basic authentication method, REST clients can access ThoughtSpot objects using username and password parameters and programmatically sign in to ThoughtSpot using the /tspublic/v1/session/login API.

Resource URL🔗

POST /tspublic/v1/session/login

Request Parameters🔗

Form parameterDescription

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 codeDescription

200

User logged in

204

Successful login

401

Login failure/unauthorized request

Obtain a token for trusted authentication🔗

If you have enabled trusted authentication on ThoughtSpot and have access to the secret key, you can send an API request to the /tspublic/v1/session/auth/token endpoint and get a login token for a ThoughtSpot user.

After you get the authentication token from ThoughtSpot via a REST API call to the /tspublic/v1/session/auth/token endpoint, use this token in your API request to the /tspublic/v1/session/login/token endpoint to authenticate and log in a user.

Just-in-time provisioning and dynamic group assignment🔗

Starting from 8.9.0.cl, the /tspublic/v1/session/auth/token API endpoint supports adding a user Just-in-Time (JIT) and dynamically assigning groups and privileges. If a user for whom you want to request an authentication token doesn’t exist in the ThoughtSpot system, you can set the autocreate and groups properties in the API call to add the user and assign groups.

Resource URL🔗

POST /tspublic/v1/session/auth/token

Request parameters🔗

Form parameterDescription

secret_key

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

username

String. The username of the user configured in ThoughtSpot.

If the user doesn’t exist in the ThoughtSpot system, you can set the autocreate flag to true to create a user account in ThoughtSpot.

email
Optional

String. Email address of the user. Specify a value for this parameter if provisioning a user just-in-time (JIT).

display_name
Optional

String. Display name of the user. Specify a value for this parameter if adding a user just-in-time (JIT).

access_level

String. User access privilege. Valid values are:

  • FULL - Creates a session with full access.

  • REPORT_BOOK_VIEW - Allows view access to the visualization or Liveboard.

id

String. GUID of the ThoughtSpot object. If you have set the access_level attribute to REPORT_BOOK_VIEW, specify the GUID of the Liveboard or visualization object.

orgid

Integer. ID of the Org to which the user belongs. This parameter is required if your ThoughtSpot instance is set as a multi-tenant environment and logically partitioned into Orgs.

  • If the user exists in ThoughtSpot and no orgid is specified, the API returns the authentication token to log the user in to their last logged-in Org.

  • If the user exists in ThoughtSpot but is not assigned to any Org, and autocreate is set to true, the user will be added to the specified Org.

  • If the user doesn’t exist in ThoughtSpot and autocreate is set to true, the user is created and added to the specified Org ID.

  • If the user already exists in the ThoughtSpot system, and the user does not belong to the specified orgid, the API returns an error.

Note

Org IDs are integers that are created automatically when a cluster administrator creates an Org. To know the Org IDs of Orgs, send a GET request to the /tspublic/v1/session/orgs API endpoint. If you have cluster administrator privileges, you can use the /tspublic/v1/org/search endpoint to get a list of all Orgs available on your cluster.

groups Optional

String. A JSON array of groups to which the user belongs. For example, ["sales", "marketing"].

  • If the user doesn’t exist in ThoughtSpot and autocreate is set to true, the user is assigned to the specified groups.

  • If the user already exists in the ThoughtSpot system and autocreate is set to false, the API ignores the values specified in the groups attribute.

  • If the user already exists in the ThoughtSpot system and autocreate is set to true, the API updates the user object.

  • If autocreate is set to true and the group names are not defined in the groups property, ThoughtSpot does not update the user object.

autocreate Optional

Boolean. When set to true, if the specified username does not exist in the ThoughtSpot system, a new user is created without a password. By default, the autocreate property is set to false.

Example request🔗

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: text/plain' \
-d 'secret_key=82749a88-1506-4cd9-803c-8316c7d41d7c&username=testUser2&access_level=FULL&groups=%5B%22sales%22%2C%20%22marketing%22%5D&autocreate=true' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/auth/token'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/auth/token

Example response🔗

If the API request is successful, ThoughtSpot returns an authentication token for the user.

Note

  • If the username specified in the API request exists in the ThoughtSpot system, the API returns the token, else it returns the user not found error.

  • If the user does not exist in ThoughtSpot and the autocreate property is set to true, the user is created. If groups and orgid attributes are defined, ThoughtSpot assigns the user to the specified groups and Org ID.

  • If the user already exists in ThoughtSpot, autocreate is set to true, and the group names are defined in the groups attribute, the user will be added to the groups specified in the API request. Similarly, if you have specified the orgid with autocreate set to true, the user will be assigned to the specified Org.

  • When autocreate is set to true, if the groups specified in the groups attribute do not exist in the specified Org ID, ThoughtSpot will create groups in the specified Org ID and assign the user to these groups.

  • The authentication token returned by ThoughtSpot can be used to access only the Org specified in the API request. If the client must be logged in to another Org, you must send another API request to get an authentication token from ThoughtSpot.

The following example shows the authentication token returned by ThoughtSpot after a successful API call.

JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCRPMFA2S0ZlNm51Qlo4NFBlZUppdzZ3PT0kMnJKaSswSHN6Yy96ZGxqdXUwd1dXZkovNVlHUW40d3FLMVdBT3hYVVgxaz0

Response codes🔗

HTTP status codeDescription

200

The authentication token is generated successfully

400

Invalid parameter value

401

Unauthorized request or invalid token

500

Token-based trusted authentication is not enabled on ThoughtSpot

Authenticate and log in with a token (Trusted authentication)🔗

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 (Recommended)

    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🔗

ParameterDescription

username

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

auth_token

String. The authentication 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 Liveboard, the redirect URL includes the host domain to which the user will be redirected, the authentication token, and the visualization and Liveboard IDs.

no_url_redirection

Boolean. By default, the API returns a 302 code and redirects the user to the requested URL. If you do not want to redirect users, set this parameter to true.

Example requests🔗

The following example shows a GET request with query parameters in the request URL:

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/plain' \
-d 'username=tsadmin&auth_token=JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCRyNGRXRmsxclVVOFY3dXJjTUNGMUh3PT0kSlZwSTZQZUl2Zm5iQjIwWlZ2Nzd2VysvMUpmTmFSL21sRDFLbTNWNWk3QT0&redirect_url=https://{ThoughtSpot-Host}/?embedV2=true#/pinboard/7a9a6715-e154-431b-baaf-7b58246c13dd%2F&no_url_redirection=false' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/login/token'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/login/token

Example response🔗

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

  • If no_url_redirection is set to true, the API returns 204 response code.

  • If no_url_redirection is set to false, the API returns a response body and redirects the user to the requested URL.

    <!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 codeDescription

200

The user is logged in successfully.

204

No URL redirection.

302

The user is redirected to the specified URL.

401

Unauthorized request or invalid token.

Log out of a user session🔗

To log a user out of the current session, use the /tspublic/v1/session/logout API.

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 codeDescription

200

User logged out

204

Successful log out of user

401

Logout failure/unauthorized request

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": "[email protected]",
  "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 codeDescription

200

Successful operation.

Switch between Orgs🔗

If your ThoughtSpot instance has multiple Orgs, you can switch between Orgs by using the /tspublic/v1/session/orgs endpoint.

Only the cluster administrator and users that belong to multiple Orgs can switch between the Orgs.

Resource URL🔗

PUT /tspublic/v1/session/orgs

Request parameters🔗

Form parameterDescription

orgid

Integer. ID of the Org object. The org ID 0 indicates Primary Org. To switch to another Org, specify the Org ID.
To know the Org IDs of the Orgs that you can access, send a GET request to the /tspublic/v1/session/orgs endpoint.

Example request🔗

cURL
curl -X PUT \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
-d 'orgid=-1' \
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/orgs'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/orgs

Example response🔗

If the API request is successful, ThoughtSpot returns the 204 response code:

Response Code
204

Response codes🔗

HTTP status codeDescription

204

Successful operation

400

Invalid parameter

403

Unauthorized request

Get Orgs for the logged-in user🔗

To get a list of Orgs for the current logged-in user, send a GET request to the /tspublic/v1/session/orgs API endpoint.

  • If the logged-in user is a cluster administrator, the API returns all active Orgs.

  • If the logged-in user belongs to more than one Org, the API returns all the active Orgs to which the user belongs.

Resource URL🔗

GET /tspublic/v1/session/orgs

Request parameters🔗

Query parameterDescription

batchsize Optional

Integer. The batch size of the Org objects returned in the API response. The system default is -1. A value of -1 implies all items starting from the offset value.

offset Optional

Integer. The batch offset value that indicates the index point starting from which the list of Org objects are retrieved. The system default is -1, which implies the first item in the list.

Example request🔗

cURL
curl -X GET \
--header 'Accept: application/json' \
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/orgs?batchsize=-1&offset=-1'
Request URL
http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/orgs?batchsize=-1&offset=-1

Example response🔗

If the API request is successful, ThoughtSpot returns a list of active Orgs for the logged-in user:

{
  "orgs": [
    {
      "orgId": 0,
      "orgName": "Primary",
      "description": "Primary Org",
      "allUserGroupId": "b25ee394-9d13-49e3-9385-cd97f5b253b4",
      "defaultAdminUserGroupId": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
      "isActive": true
    },
    {
      "orgId": 1776311864,
      "orgName": "my-org1",
      "description": "",
      "allUserGroupId": "a4ef5fe2-0f90-4632-bd2c-d447428495b8",
      "defaultAdminUserGroupId": "203182f3-3ae1-422f-ae65-30c72f92b665",
      "isActive": true
    },
    {
      "orgId": 255226812,
      "orgName": "my-org2",
      "description": "",
      "allUserGroupId": "d15f3347-1e3a-48a9-bbb5-c31c368b054e",
      "defaultAdminUserGroupId": "1ce55b07-42f1-434f-b1e5-a71b2f78289d",
      "isActive": true
    },
  ],
  "canAdministerAllOrgs": true,
  "currentOrgId": 0
}

Response codes🔗

HTTP status codeDescription

204

Successful operation

403

Unauthorized request

Get Orgs for a specific user🔗

To get a list of Orgs for a specific user, send a GET request to the tspublic/v1/session/orgs/users/{userid} API endpoint.

Resource URL🔗

GET /tspublic/v1/session/orgs/users/{userid}

Request parameters🔗

ParameterTypeDescription

userid

Path parameter

String. GUID of the user.

orgScope

Query

String. The Org scope. Specify ALL to set the Org scope to all Orgs.

Example request🔗

cURL
curl -X GET \
--header 'Accept: application/json' \
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/orgs/users/59481331-ee53-42be-a548-bd87be6ddd4a?orgScope=ALL'
Request URL
http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/session/orgs/users/59481331-ee53-42be-a548-bd87be6ddd4a?orgScope=ALL

Example response🔗

If the API request is successful, ThoughtSpot returns a list of active Orgs for the specified user GUID:

{
  "orgs": [
    {
      "orgId": 255226812,
      "orgName": "Primary",
      "description": "Primary Org",
      "isActive": true
    }
  ],
  "canAdministerAllOrgs": false,
  "currentOrgId": 255226812
}

Response codes🔗

HTTP status codeDescription

204

Successful operation

400

Invalid parameter

403

Unauthorized request

Set a home Liveboard🔗

To set a Liveboard as a home Liveboard for a user account, send a POST request to the /tspublic/v1/session/homepinboard API endpoint. If a home Liveboard 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 parameterDescription

id

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

userid Optional

String. GUID of the user account for which you want to set the home Liveboard. If the userid attribute is not defined, ThoughtSpot sets the home Liveboard of the currently 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 codeDescription

204

The specified Liveboard is set as a home Liveboard.

403

The Liveboard with the given ID is not accessible.

401

Unauthorized request or invalid token.

404

The specified Liveboard was not found.

Get details of the home Liveboard🔗

To get the GUID of Liveboard that is currently set as a home Liveboard, 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 Liveboard is set in the currently logged-in user’s account, the API returns the GUID of the Liveboard set as a home Liveboard:

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

Response codes🔗

HTTP status codeDescription

200

Successful operation.

Remove a home Liveboard🔗

To remove the home Liveboard setting from the currently 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 Liveboard is set in the currently logged-in user’s account, the API returns the following response:

Response Code
200

Response codes🔗

HTTP status codeDescription

200

Successful operation.