Creating and listing workspaces in Management API

Creating and listing workspaces in Management API#

This guide explains how to create and list workspaces (called stacks in the Management API) with the Management API.

Note

Users with the Workspace Manager role can create and list workspaces within their accessible scope using a Token key generated with their own credentials. All operations are automatically scoped to the workspaces the user has access to. For more information on the Workspace Manager role, see Managing user permissions.

Prerequisites#

  • To create or update a workspace through Management API with a scoped API key (independently of the Workspace Manager role), use a key with the workspace: write scope. This includes API keys generated in the Adverity user interface. For more information, see Authorizing to Management API.

  • Deleting a workspace is not covered by API key scopes. The user the key belongs to must have Administrator permissions in the root workspace; the workspace: write scope alone does not grant delete access.

Listing existing workspaces#

To list existing workspaces, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/stacks/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you obtain the list of available workspaces in Management API and their IDs in the response.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/stacks/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Note

The response includes a uuid field for each workspace. You can use this UUID to filter the list, as described below.

Filtering workspaces by UUID#

To retrieve a specific workspace by its UUID, follow these steps:

  1. Create a GET request to the following endpoint, replacing {{WORKSPACE_UUID}} with the UUID of the workspace:

    https://{{INSTANCE}}/api/stacks/?uuid={{WORKSPACE_UUID}}

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you obtain the workspace matching the specified UUID.

The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/stacks/?uuid={{WORKSPACE_UUID}}' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Listing available storages#

To list available storages, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/storage/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you obtain the list of available storage options.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/storage/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Creating a new workspace#

To create a new workspace (called Stack in Management API), follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/stacks/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the following code as raw JSON input, and then replace the placeholder values as necessary.

    {
   "datalake_id": STORAGE_ID,
   "name":"NAME_OF_NEW_WORKSPACE",
   "parent_id": PARENT_ID
}

    Replace the following:

    • STORAGE_ID: Include the value of the parameter id in the API response where you list available storages. To obtain the described list, follow the procedure in Listing available storages.

    • NAME_OF_NEW_WORKSPACE: Choose any name for your new workspace which does not currently exist.

    • PARENT_ID: Optional. The ID of the workspace to set as the parent of the new workspace. The specified workspace becomes the parent of the new workspace, which inherits some of its configuration. If omitted, the workspace is created under the default parent workspace. To find the PARENT_ID, search for the value of the parameter id in the response to the request described in Listing existing workspaces.

  5. Send the request.

As a result, you created a new workspace through the Management API.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/stacks/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datalake_id": STORAGE_ID, "name":"NAME_OF_NEW_WORKSPACE", "parent_id": PARENT_ID}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Deleting a workspace#

To delete a workspace through Management API, follow these steps:

  1. Create a DELETE request to the following endpoint:

    https://{{INSTANCE}}/api/stacks/{{STACK_SLUG}}/

    Replace {{STACK_SLUG}} with the workspace name in lowercase, with spaces replaced by hyphens. For example, a workspace named My Workspace has the slug my-workspace. You can also find the slug as the value of the parameter slug in the response to the request described in Listing existing workspaces.

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you deleted the workspace through the Management API.

Warning

Deleting a workspace also deletes all its child workspaces and removes every authorization granted anywhere in that workspace tree. This action is not covered by API key scopes — the workspace: write scope alone does not grant delete access, regardless of how the key was generated. The user the key belongs to must have Administrator permissions in the root workspace.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request DELETE 'https://{{INSTANCE}}/api/stacks/{{STACK_SLUG}}/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Contents