Org administration and management via REST API

Org administration and management via REST API

To administer and manage Orgs, you can use the UI workflows or REST API v1 endpoints. This article describes the REST API v1 operations available for Org provisioning and management.

Org CRUD operations via REST API v1🔗

To create an Org on a multi-tenant ThoughtSpot instance, you require cluster administrator privileges. By default, ThoughtSpot sets the administrator of the Primary Org as a cluster administrator. The cluster administrator can create Orgs using the Org API endpoints.

  1. Log in to your ThoughtSpot instance as a cluster administrator.

  2. To view the REST API v1 endpoints, go to https://<your-ts-cluster-host>/external/swagger/.

  3. For Orgs CRUD operations, use the /tspublic/v1/org/ endpoints. For all Org operations, you must set the org scope to ALL in your API request and pass it as a query parameter in the request URL.

Switch between Orgs🔗

A cluster administrator can access all Org objects and apply configuration changes. Before performing any operation on the objects in an Org, the administrator must switch to the appropriate Org context. The cluster administrator can switch between Orgs using the Orgs switcher in the UI or via a REST API call to the /tspublic/v1/session/orgs endpoint.

Org users that belong to more than one Org can also use the /tspublic/v1/session/org API endpoint to switch the Org context.

For more information, see Switch between Orgs.

Manage users and groups🔗

On a multi-tenant instance, the cluster and Org administrators can create users and associate these users to Orgs and groups within an Org. The cluster administrator can perform CRUD operations on user and Org objects, whereas the Org administrator can create users and groups, and assign users to groups within the context of their Org workspace.

Operation typeAPI endpoints to use

User provisioning

To create users, use the POST /tspublic/v1/user/ API endpoint.
This endpoint also allows assigning a user to Orgs.

To add multiple users to an Org in bulk, use the POST /tspublic/v1/user/addtoorg API endpoint.

To remove a user from an Org, use the DELETE /tspublic/v1/user/{userid} endpoint. If a user belongs only to the Org specified in the DELETE request, the user will be deleted from the Org and ThoughtSpot system. If the user belongs to more than one Org, the DELETE operation removes the user only from the Org specified in the API request. To remove the user from the ThoughtSpot system and all Orgs, you must set the orgid to -1 in your API request.

Group provisioning

To create a group in an Org, switch to the appropriate Org context and then send an API request to the /tspublic/v1/group/ endpoint. If you do not switch the Org context, the group will be created in the Org context that you are currently logged in to.


If your deployment uses the trusted authentication method to authenticate users, you will notice that the POST /tspublic/v1/session/auth/token endpoint allows you to send the orgid in the request body. If a user is mapped to a specific org, you can pass the orgid in the API request to obtain an authentication token and log in the user to the relevant Org context.
You can also use the POST /tspublic/v1/session/auth/token API call to provision a user just-in-time and dynamically assign groups and privileges. For more information, see Trusted authentication and Obtain an authentication token.

Query operations to get Orgs

To get a list of Orgs for the currently logged-in user, use the /tspublic/v1/session/orgs API endpoint.
To get Orgs for a specific user, use the /tspublic/v1/session/orgs/users/{userid} endpoint. For this API request, you must set the Org scope to ALL.