REST API v2.0 authentication

REST API v2.0 authentication

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

Basic authentication

In this method, REST clients can access ThoughtSpot objects using username and password parameters.

Bearer token authentication

In this method, the REST clients obtain a bearer access token to authenticate to ThoughtSpot. The access token is a string, which you must include in the Authorization header to authorize your API requests.

Trusted authentication

In this method, the REST clients must obtain an authentication token to sign in to a ThoughtSpot instance.

Administrators can request an authentication token on behalf of another user by providing the secret key as input in the API request. The API users must pass the token obtained from ThoughtSpot in the Authorization header of their requests.

The trusted authentication method also supports creating a user just-in-time and assigning privileges.

Basic authentication🔗

In the basic authentication method, user credentials are sent in the API request.

To sign in to ThoughtSpot and create a session, REST clients must send a POST request with the following attributes to the /api/rest/2.0/auth/session/login API endpoint:

ParameterDescription

username

String. Username of the ThoughtSpot user.

password

String. The password of the user account.

org_identifier

String. Name of ID of the Org. If no Org ID is specified, the user will be logged into the Org context of their previous session.

remember_me

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

Example 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

Example response🔗

If the login is successful, ThoughtSpot returns the 204 response code.

Response codes🔗

HTTP status codeDescription

204

Successful logon

400

Bad request
Invalid username or password

401

Unauthorized success

500

Operation failed

Bearer token authentication🔗

For OAuth 2.0 bearer token-based authorization, you must obtain an OAuth access token. You can obtain a token that grants read-only access to a ThoughtSpot metadata object or full access to the ThoughtSpot app.

Get a token for full access🔗

To get an access token that grants full access to ThoughtSpot, send a POST request to the /api/rest/2.0/auth/token/full endpoint with the following parameters in the request body:

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 that you want to access. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user.

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": "Guest@123!"
  "org_id": 1,
  "validity_time_in_sec": 86400
}'
Request URL
POST {ThoughtSpot-Host}/api/rest/2.0/auth/token/object

Example response🔗

If the API request is successful, ThoughtSpot returns the access token in the response body.

{
  "token": "{access-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": "59481331-ee53-42be-a548-bd87be6ddd4a",
  "valid_for_username": "tsUserA"
}

Response codes🔗

HTTP status codeDescription

204

Successful logon

400

Bad request
Invalid parameter

401

Unauthorized success

403

Forbidden access

500

Operation failed

Get an access token to view a specific object🔗

To get an OAuth token to access a specific metadata object in ThoughtSpot, send a POST request to the /api/rest/2.0/auth/token/object endpoint with the following attributes in the request body:

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 that you want to access. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user.

Example request🔗

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
  "username": "tsUserA",
  "object_id": "bea79810-145f-4ad0-a02c-4177a6e7d861",
  "password": "Guest@123!"
}'
Request URL
POST {ThoughtSpot-Host}/api/rest/2.0/auth/token/object

Example response🔗

If the API request is successful, ThoughtSpot returns the access token in the response body.

{
  "token": "{access-token}",
  "creation_time_in_millis": 1674665089872,
  "expiration_time_in_millis": 1674665389872,
  "scope": {
    "access_type": "REPORT_BOOK_VIEW",
    "org_id": 0,
    "metadata_id": "9bd202f5-d431-44bf-9a07-b4f7be372125"
  },
  "valid_for_user_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
  "valid_for_username": "tsUserA"
}

Response codes🔗

HTTP status codeDescription

204

Successful logon

400

Bad request
Invalid parameter

401

Unauthorized success

403

Forbidden access

500

Operation failed

Trusted authentication🔗

Trusted authentication allows an authenticator service to request tokens on behalf of users who require access to the ThoughtSpot content embedded in a third-party application.

The token issued from ThoughtSpot can be used to log in a user. By default, the token is valid for 300 seconds and the token expiration duration is configurable. Note that the token is necessary only during the login process, after which any request to ThoughtSpot will include session cookies identifying the signed-in user.

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.

The token generation API endpoints also allow creating a user just-in-time and dynamically assign privileges, groups, and Org to the new user.

Get an access token for full access🔗

To get an access token that grants full access to ThoughtSpot, send a POST request with the following 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 provided by the ThoughtSpot server. ThoughtSpot generates this secret key when trusted authentication is enabled.

org_id
Optional

Integer. If the Orgs feature is enabled on your instance, specify the ID of the Org to which the user belongs. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user.

validity_time_in_sec
Optional

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

auto_create
Optional

Boolean. Creates a user if the specified username is not already available in ThoughtSpot. The default value is false.

group_identifiers
Optional

String. GUID or name of the groups to which the user belongs. This attribute can be used in conjunction with auto_create to dynamically assign groups and privileges to a user.

Example request🔗

The following example shows the code sample to request an object access token for a ThoughtSpot user:

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

The following example shows the code sample to obtain a token for a user, which is being provisioned just-in-time:

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full' \
  -H 'Authorization: Bearer {admin-access-token}'\
  -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"
  ]
}'

Example response🔗

If the API request is successful, ThoughtSpot returns the token in the response body.

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

Response codes🔗

HTTP status codeDescription

204

Successful logon

400

Bad request
Invalid parameter

401

Unauthorized success

403

Forbidden access

500

Operation failed

Get an authentication token for object access🔗

To get a token that grants a READ-ONLY access to a specific metadata object, send a POST request with the following attributes to the /api/rest/2.0/auth/token/object API 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 provided by the ThoughtSpot server. ThoughtSpot generates this secret key when trusted authentication is enabled.

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 to which the user belongs. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user.

validity_time_in_sec
Optional

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

auto_create
Optional

Boolean. Creates a user if the specified username is not already available in ThoughtSpot. The default value is false.

group_identifiers
Optional

String. GUID or name of the groups to which the user belongs. This attribute can be used in conjunction with auto_create to dynamically assign groups and privileges to a user.

Example request🔗

The following example shows the code sample to request an object access token for a ThoughtSpot user:

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

The following example shows the code sample to obtain a token for a user, which is being provisioned just-in-time:

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object' \
  -H 'Authorization: Bearer {admin-access-token}'\
  -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"
  ]
}'

Example response🔗

If the API request is successful, ThoughtSpot returns a token for the specified username in the response body.

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

Response codes🔗

HTTP status codeDescription

204

Successful logon

400

Bad request
Invalid parameter

401

Unauthorized success

403

Forbidden access

500

Operation failed

Log in to ThoughtSpot🔗

REST clients can log in to ThoughtSpot using their username and password or the token obtained from ThoughtSpot. If you send an API request with usersame, password, and bearer token in the Authorization header, the user credentials take precedence over the token specified in the Authorization header.

curl -X POST \
 --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/session/login' \
 --header 'Authorization: Bearer dHNVc2VyQTpKSE5vYVhKdk1TUlRTRUV0TWpVMkpEVXdNREF3TUNSRmIxazVaa3BQTjFGR1VYTlRXa2xRUTJwaFVqbDNQVDBrTjBGR01FSlhiVGhzWmpaRWRYWjJWMkZYTm5KTlRGSlRibTlUTURCQ1V6RkdlR3N6TWpCbFRFVlhjejA='

By default, the token obtained from ThoughtSpot is valid for 300 seconds. You can configure the token expiry duration as per your requirement or request a new token and use it in your subsequent API calls. If a REST client tries to make an API call with an expired token, the server returns an error.

Tip

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 cookies along with the other aspects of the particular REST API call.

Revoke 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 {admin_access_token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_identifier": "tsUserA,
  "token": {access_token_user}
}'
Request URL
https://{ThoughtSpot-host}/api/rest/2.0/auth/token/revoke

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.

Response codes🔗

HTTP status codeDescription

204

Successful token revocation

400

Invalid request

401

Unauthorized access

403

Forbidden access

500

Failed operation or unauthorized request

View session information🔗

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

Resource URL🔗

GET /api/rest/2.0/auth/session/user

Request parameters🔗

None

Example request🔗

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

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

Response codes🔗

HTTP status codeDescription

200

Successful retrieval of session information

400

Invalid request

401

Unauthorized request

500

Failed operation

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

Resource URL🔗

POST /api/rest/2.0/auth/session/logout

Example request🔗

cURL
curl -X POST \
  --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/session/logout' \
  -H 'Content-Type: application/json'\
  -H 'Accept-Language: application/json'
Request URL
https://{ThoughtSpot-host}/api/rest/2.0/auth/session/logout

Example response🔗

If the API request is successful, the currently logged-in user is signed out of ThoughtSpot.

Response codes🔗

HTTP status codeDescription

204

The user is logged out of ThoughtSpot

500

Failed operation