How do I authenticate to ThoughtSpot's REST API v2, and why does it return 401?

To call ThoughtSpot's REST API v2, request a bearer token from /api/rest/2.0/auth/token/full on your server and send it as Authorization: Bearer on every call. The common causes of a 401 are a missing or expired token, a token issued for another Org (ThoughtSpot's term for a tenant), or a user who can't access the object.

Checked against REST API SDK 2.29.1 and the ThoughtSpot Cloud 26.10.0.cl documentation, October 2026.

Bearer authentication is the HTTP scheme where each request carries a token in the Authorization header, and the server treats whoever holds the token as that user. ThoughtSpot REST API v2 issues bearer tokens from /api/rest/2.0/auth/token/full. Each token belongs to one user and one Org, and lasts 300 seconds by default.

What should you check when you compare tools?

Once analytics is in your product, you'll automate it: create users at sign-up, deploy from CI, ask questions from your backend. ThoughtSpot's REST API v2 issues bearer tokens scoped to a user and an Org, and covers users, groups, roles, Orgs, connections, content import and export (TML), sharing and security settings, schedules, webhooks, variables and Spotter conversations (REST API v2 reference).

Ask any vendor:

• Can a backend service get a token without a password or a browser session?
• Can a token be limited to one customer's tenant?
• Which of my jobs have an API: user provisioning, content deployment, AI questions?

What does the error look like?

HTTP/1.1 401
{"error":{"message":{"debug":"Unauthorized: The client must authenticate itself to get the requested response."}}}

ThoughtSpot defines it as: "Indicates an unauthorized request. Check if you have the required credentials and object access to send the API request" (status codes).

First, find out who the token belongs to

curl -X GET 'https://<TS_HOST>/api/rest/2.0/auth/session/user' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Accept: application/json'

If this returns 401, the token is the problem (causes 1 and 2). If it returns a user, check the Org and object access (causes 3 and 4).

The causes, in order

1. A missing or malformed header. Send Authorization: Bearer <token>, Accept: application/json and Content-Type: application/json on every call (a wrong Content-Type returns 415). A User-Agent header "is required for all requests"; most clients add one, but code, "especially .NET", must set it (request headers).

curl -X POST 'https://<TS_HOST>/api/rest/2.0/metadata/search' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{ "metadata": [{ "type": "LIVEBOARD" }] }'

2. An expired token. "The default duration is 300 seconds" (REST API authentication), and a bearer token's lifespan "does not ever extend" (session length). Request a longer validity_time_in_sec, or a new token per job:

curl -X POST 'https://<TS_HOST>/api/rest/2.0/auth/token/full' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "username": "<SERVICE_USER>",
    "secret_key": "<SECRET_KEY>",
    "org_id": <ORG_ID>,
    "validity_time_in_sec": 3600
  }'

Without org_id, ThoughtSpot takes the Org from the secret key, or uses the user's last logged-in Org. Request the token with the target Org's org_id, as above (REST auth: Orgs).

4. No access to the object. A 401 can also mean the user doesn't have the "privileges to create or modify the data objects" (troubleshooting: 401). Share the object with the user, or grant the privilege.

Logging in from a script? Use secret_key, not a password: with MFA on, password logins "will return an error" (REST auth overview).

How do I check it worked?

/auth/session/user returns the user and Org you expect, and the original call returns 200.

Still failing?

• 403 instead of 401. Privileges or account status, not the token.
• 415. Check the Content-Type header.
• 429. Rate limits: 100 requests per second per client IP and, from 26.11.0.cl on instances with Orgs, 50 per Org (rate limits).

How do I explain this to my team?

How can I try this before I commit?

Start a free ThoughtSpot Embedded trial.

Related

• REST API v2: get started
• REST API v2 authentication
• REST API v2 reference

Subscribe to our blog