# REST API v1 authentication > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/api-auth-session # REST API v1 authentication > **IMPORTANT:** The REST API v1 endpoints are deprecated and replaced with the REST API v2 endpoints. Your existing integrations with REST API v1 endpoints will continue to function without disruption until further notice. ThoughtSpot strongly recommends migrating your integrations to the REST API v2 endpoints. To create, access, and modify ThoughtSpot objects and resources through the REST API, you must log in as an authorized user. A successful login operation returns session cookies from the ThoughtSpot system, which must be included in subsequent REST API calls. When using the REST API through a web browser, ThoughtSpot recommends that you use the [SAML SSO]({{navprefix}}/{{configure-saml}}) or [trusted authentication]({{navprefix}}/{{trusted-authentication}}) service to authenticate to ThoughtSpot. A successful login using the Visual Embed SDK via either of those two methods will establish the session within the web browser. ## 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 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 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 | A successful login returns a session cookie that can be used in your subsequent API calls. For more information, see [Session cookies for subsequent API calls]({{navprefix}}/{{api-auth-session}}#sessionCookies). > **NOTE:** If MFA is enabled on your ThoughtSpot instance then basic authentication with only username and password will return an error. Contact ThoughtSpot Support for assistance. Embedded users authenticating to ThoughtSpot with basic authentication are recommended to switch to AuthType.TrustedAuthTokenCookieless. MFA can be enabled on your instance only if Identity and Access Management (IAMv2) is already enabled. ## Trusted authentication For trusted authentication, you must obtain a token from ThoughtSpot via `/tspublic/v1/session/auth/token` and send it in your login request to the `/tspublic/v1/session/login/token` API endpoint. ### Obtain a token for trusted authentication If you have enabled [trusted authentication]({{navprefix}}/{{trusted-auth-secret-key}}#trusted-auth-enable) 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 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 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`. | | `jwt_user_options` _Optional_ | A map of JSON parameters to define security entitlement for a given user. Use this option if you plan to implement [Attribute-Based Access Control]({{navprefix}}/{{abac-user-parameters}}). View example ```JSON { "parameters": [ { "runtime_filter": { "row1": "Region", "op1": "IN", "val1": "["West", "Southwest"]", "row2": "Sales", "op2": "EQ", "val2": "[bags]" } }, { "runtime_sort": { "sortCol1": "Sales", "asc1": true, "sortCol2": "Region", "asc2": false } }, { "runtime_param_override": { "param1": "Integer Range Param", "paramVal1": "5", "param2": "Date List Param", "paramVal2": "1662361200" } } ], "metadata": [ { "type": "LIVEBOARD", "identifier": "d084c256-e284-4fc4-b80c-111cb606449a" } ] } ``` | #### Example request cURL ```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 code | Description | | --- | --- | | **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]({{navprefix}}/{{session-api}}#session-authToken) 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 | Parameter | Description | | --- | --- | | `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:///?authtoken=&embedApp=true&primaryNavHidden=true#/embed/viz//` 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 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 ```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 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 ```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. ```HTML
``` #### Response codes | HTTP status code | Description | | --- | --- | | **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. | ## Session cookies for subsequent API calls If the login operation is successful, the API returns cookie details 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 The session cookie is automatically set in the request header when you make your subsequent API calls via a web browser. REST clients in a non-browser environment must pass this cookie in the request header in their subsequent API calls. ## Make a test API call You can make a test API call to verify if your token is valid and allows access to ThoughtSpot objects. For example, you can send a `GET` request `/tspublic/v1/metadata/listvizheaders` to fetch the visualization headers of a Liveboard. Note that if you are using a Web browser or Postman to make a REST API call, the session cookie obtained from the `/tspublic/v1/session/login/token` or `/tspublic/v1/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 curl -X GET \ --header 'Accept: text/html' \ --header 'X-Requested-By: ThoughtSpot' \ --header 'Cookie: JSESSIONID=fc3424f9-d3f0-4a24-bd33-400fd826cac7; clientId=70cf1328-af97-40b2-9bd5-1c520e133963' \ 'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/listvizheaders?id=d084c256-e284-4fc4-b80c-111cb606449a' ``` Once the session is established in the browser, you can set the `withCredentials: true` property for any `XMLHttpRequest` object or `credentials: "include"` as part of a `Fetch` object to pass the cookies along when making REST API requests: ```javascript // Simple XMLHttpRequest var xhr = new XMLHttpRequest(); xhr.withCredentials = true; // Using Fetch with Promises return async fetch( apiFullEndpoint, { method: 'GET', headers: { "Accept": "application/json", "X-Requested-By": "ThoughtSpot" }, credentials: "include" }) ``` > **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 session cookies along with the other aspects of the REST API call. ## 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 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 |