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 operations available for Org provisioning and management.

Org CRUD 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 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 and setting its status as active or inactive.

  • To delete an Org object, send a DELETE request to the /tspublic/v1/org/ endpoint with Org ID or name in the request body.

REST API v2.0 endpoints🔗

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

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 typeREST API v1 endpointsREST 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:

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

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