Org administration

Table of Contents

Get started with Orgs
Org management operations
- REST API v2.0 endpoints
- REST API v1 endpoints
Manage users and groups

To administer and manage Orgs, you can use the UI workflows or REST API endpoints.

This article describes the REST API operations available for Org provisioning and management.

Get started with Orgs🔗

Configure your ThoughtSpot instance as a multi-tenant cluster. If the Orgs feature is enabled on your cluster, a Primary Org is created by default, and you will be logged in to the Primary Org context.

If you do not see the Orgs feature enabled on your instance, contact ThoughtSpot Support.
Log in to your application instance as an administrator.
Create Orgs in the Admin page of the UI or via REST API.

To create and manage Orgs, you must set the Org context to All. To do this, you can switch to the All Orgs tab in the Admin page of UI or pass the Org scope ALL in your API requests to Orgs API endpoints. For more information, see Org API.
Create users and map the users to Orgs.

You can create an administrator profile for each Org and let these Org administrators manage users, groups, and role privileges in their respective Orgs.

Note that ThoughtSpot allows provisioning groups only within the context of an Org. You must ensure that ThoughtSpot users are mapped to appropriate Orgs and the groups within these Orgs for user access control and data security.

Org management operations🔗

To create an Org on a multi-tenant ThoughtSpot instance, you need cluster administrator privileges. By default, ThoughtSpot sets the administrator of the Primary Org as a cluster administrator. Only cluster administrators are allowed to perform CRUD operations on Org objects.

REST API v2.0 endpoints🔗

For Orgs CRUD operations, you can also use the following REST API v2.0 Org endpoints:

REST API v1 endpoints🔗

For Orgs CRUD operations, use the /tspublic/v1/org/ endpoints. To access Org API endpoints, you must log in to ThoughtSpot as a cluster administrator:

Note that 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.

To create an Org, send a POST request to the /tspublic/v1/org/ endpoint with the Org name and description text in the request body.

If the API operation is successful, ThoughtSpot creates an Org and assigns a system-generated number as Org ID.
To view the Orgs configured on a ThoughtSpot instance, use the /tspublic/v1/org/search or GET /tspublic/v1/org/ API endpoint.
To edit the properties of an Org object, use the PUT /tspublic/v1/org/ endpoint.

The PUT request allows modifying the name and description properties of an Org object.
To delete an Org object, send a DELETE request to the /tspublic/v1/org/ endpoint with Org ID or name in the request body.

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 these Orgs. The cluster administrator can perform CRUD operations on Org objects at the All Orgs level and assign users, whereas the Org administrator can create users and groups within the context of their Org workspace.

Note

The /tspublic/v1/session/orgs REST API v1 endpoint allows administrators to switch between Org contexts. For REST API v2 operations, the Org context is determined based on the authentication token used by the user in their API requests. Users must log in to the appropriate Org context from which they want to send API requests.

Operation type REST API v1 endpoints REST API v2 endpoints

Operation type	REST API v1 endpoints	REST API v2 endpoints
Authentication	Basic authentication To log in to a specific Org context with basic authentication, specify the Org ID in the `/tspublic/v1/session/login` API request. Token-based authentication For trusted authentication, use the `/tspublic/v1/session/auth/token` API endpoint. If a user is mapped to a specific org, you can pass the `orgid` in the API request to obtain an authentication token to log in the user to the relevant Org context. You can also create a user just-in-time and assign Orgs, groups, and privileges in this API call. For more information, see REST API v1 authentication.	Basic authentication To log in to a specific Org context with basic authentication, specify the Org ID in the `/api/rest/2.0/auth/session/login` API request. Token-based authentication Use the following API endpoints: `/api/rest/2.0/auth/token/object` `/api/rest/2.0/auth/token/full` These above endpoints also support just-in-time provisioning of users to Orgs and groups. For more information, see REST API v2 authentication.
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 `/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 from only 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.	To create users and assign users to one or several Orgs, use the `/api/rest/2.0/users/create` API endpoint. To assign an existing user to new Orgs or remove a user from an Org, use the `/api/rest/2.0/users/{user_identifier}/update` API endpoint.
Group provisioning	To create a group in an Org, log in to the Org context or switch to the Org context and send an API request to the `/tspublic/v1/group/` endpoint.	To create a group in an Org, use the `/api/rest/2.0/groups/create` API endpoint.
Fetching 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. Set the Org scope to `ALL` to get all Orgs for a given user.	The REST API v2 endpoints allow you to perform query operations to get Org details: To get a list of all Orgs on the cluster, use `/api/rest/2.0/orgs/search` (Requires cluster administrator privileges) To get Org details for a user, use `/api/rest/2.0/users/search` To get Org details for a group, use `/api/rest/2.0/groups/search`

Authentication

Basic authentication
To log in to a specific Org context with basic authentication, specify the Org ID in the /tspublic/v1/session/login API request.

Token-based authentication
For trusted authentication, use the /tspublic/v1/session/auth/token API endpoint. If a user is mapped to a specific org, you can pass the orgid in the API request to obtain an authentication token to log in the user to the relevant Org context.
You can also create a user just-in-time and assign Orgs, groups, and privileges in this API call.

For more information, see REST API v1 authentication.

Basic authentication
To log in to a specific Org context with basic authentication, specify the Org ID in the /api/rest/2.0/auth/session/login API request.

Token-based authentication
Use the following API endpoints:

These above endpoints also support just-in-time provisioning of users to Orgs and groups. For more information, see REST API v2 authentication.

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 /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 from only 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.

To create users and assign users to one or several Orgs, use the /api/rest/2.0/users/create API endpoint.

To assign an existing user to new Orgs or remove a user from an Org, use the /api/rest/2.0/users/{user_identifier}/update API endpoint.

Group provisioning

To create a group in an Org, log in to the Org context or switch to the Org context and send an API request to the /tspublic/v1/group/ endpoint.

To create a group in an Org, use the /api/rest/2.0/groups/create API endpoint.

Fetching 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. Set the Org scope to ALL to get all Orgs for a given user.

The REST API v2 endpoints allow you to perform query operations to get Org details:

To get a list of all Orgs on the cluster, use /api/rest/2.0/orgs/search (Requires cluster administrator privileges)
To get Org details for a user, use /api/rest/2.0/users/search
To get Org details for a group, use /api/rest/2.0/groups/search