Group management APIs

With the Databand group management APIs, you can automate managing users within groups. You can also make sure that they have the correct access to sources, pipelines, and projects without having to manually manage each user's permissions through the Databand’s UI. The following endpoints are available:

Listing all groups
Listing all members in a group
Adding users to groups
Listing all groups for a specific user
Deleting a user from a group

Listing all groups

The request retrieves a list of defined groups in the system. Each group includes associated asset information.

Endpoint and query parameters

To list all groups in the system, send the request by using the GET method. The endpoint is provided in the following format:

Table 1. Method and the example of an endpoint to which a request is sent.

Method	Endpoint
`GET`	`<YOUR_DATABAND_DOMAIN>/api/v1/external_group/list_groups?page[number]=1&page[size]=20`

Table 2. Query parameters

Query parameters	Description	Example
`page[number]`	Specifies which page of results to retrieve	`page[number]=1`
`page[size]`	Specifies the number of results to return per page	`page[size]=20`

Example response and parameters

After you send the request, the endpoint responds with the following type of information:

Example response

{
  "data": [
    {
      "assets": [
	    {
          "asset_id": 2,
          "name": "test",
          "source_name": "source_name",
          "source_type": "source_type"
        }
      ],
      "created_at": null,
      "last_modified": null,
      "group_id": 123,
      "group_name": "test1"
    },
	{
      "assets": null,
      "created_at": "2024-11-11T10:30:00Z",
      "last_modified": "2024-11-12T14:45:00Z",
      "group_id": 456,
      "group_name": "test2"
    }
  ],
  "meta": {
    "total": 2
  }
}

Table 3. Query results and their description

Field	Field	Type	Description
`data`		array	The details of each group
`assets`		object	The asset or assets associated with the group
	`asset_id`	number	A unique identifier for the asset
	`name`	string	The name of the asset
	`source_name`	string	The name of the source
	`source_type`	string	The type of the source
`created_at`		string	The date and time when the group was created
`group_id`		number	A unique identifier for the group
`last_modified`		string	The date and time when the group was last modified
`group_name`		string	The name of the group
`meta`		object	The object used for providing the number of groups listed in the response
	`total`	string	The number of groups listed in the response

Listing all members in a group

The request retrieves a list of all users within a specified group.

Endpoint and query parameters

To list all users in the system, send the request by using the GET method. The endpoint is provided in the following format:

Table 4. Method and the example of an endpoint to which a request is sent.

Method	Endpoint
`GET`	`<YOUR_DATABAND_DOMAIN>/api/v1/external_group/users?group_name=some_group`

Table 5. Query parameters

Query parameters	Description	Example
`group_name`	The name of the group whose members you want to list.	`sample_group_name`

Example response and parameters

After you send the request, the endpoint responds with the following type of information:

Example response

[
    {
        "access_level": "Admin",
        "last_modified": "2024-11-10T21:28:08.334852+00:00",
        "user_email": "blu@email.com"
    }, 
    {
        "access_level": "ReadOnly",
        "last_modified": "2024-11-10T21:28:08.334859+00:00",
        "user_email": "blu@email.com"
    } 
]

Table 6. Query results and their description

Field	Type	Description
`access_level`	string	The user’s access level within the group
`last_modified`	string	The date and time the user’s access level was last modified
`user_email`	string	The email of the user within the group

Adding users to groups

The request adds specified users to groups.

Endpoint and query parameters

To add users to groups, send the request by using the POST method. The endpoint is provided in the following format:

Table 7. Method and the example of an endpoint to which a request is sent.

Method	Endpoint
`POST`	`<YOUR_DATABAND_DOMAIN>/api/v1/external_group`

Example request body:

{
  "users_to_groups":{
    "username@email.com":["group1"]
    }
}

Table 8. Query parameters

Query parameters	Description	Example format
`users_to_groups`	A JSON object that contains user emails and the groups to which we want to add them.	{"user_email": ["group_name1", "group_name2"]}

Let's imagine that we need to assign the following users to the following groups:

useremail1 - group1, group2, group3
useremail2 - group2, group4
useremail3 - group1, group3, group5

The request for such a scenario would look like this:

Example request

{
    "users_to_groups": {
        "user1@email.com": ["group1", "group2", "group3"],
        "user2@email.com": ["group2", "group4"],
        "user3@email.com": ["group1", "group3", "group5"]
    } 
}

Example response and parameters

After you send the request, the endpoint responds with the following type of information:

{
  "groups_not_found": [],
  "users_not_found": [],
  "num_of_rows_added": 8
}

Table 9. Query results and their description

Field	Type	Description
`groups_not_found`	array of strings	The group names that were not found in the system.
`users_not_found`	array of strings	The user emails that were not found in the system.
`num_of_rows_added`	number	The number of successful additions that were made. From the example that is provided in the Example response section we learn that all the users were added to the groups (none of them was assigned to any of the groups earlier).

Listing all groups for a specific user

The request returns all groups that are associated with a specific user.

Endpoint and query parameters

To list all groups for a specific user, send the request by using the GET method. The endpoint is provided in the following format:

Table 10. Method and the example of an endpoint to which a request is sent.

Method	Endpoint
`GET`	`<YOUR_DATABAND_DOMAIN>/api/v1/external_group/groups?user_email=user@email.com`

Table 11. Query parameters

Query parameters	Description	Example format
`user_email`	The email of the user whose groups are being requested.	user_email=user@email.com

Example response and parameters

After you send the request, the endpoint reponds with the following type of information:

Example response

[
{
  "group_id": 345,
  "group_name": "test2"
}
]

Table 12. Query results and their description

Field	Type	Description
`group_id`	number	A unique identifier for the group
`group_name`	string	The name of the group

Deleting a user from a group

The request removes a specified user from a specified group.

Endpoint and query parameters

To delete a user from a group, send the request to the endpoint by using the DELETE method. The endpoint is provided in the following format:

Table 13. Method and the example of an endpoint to which a request is sent.

Method	Endpoint
`DELETE`	`<YOUR_DATABAND_DOMAIN>/api/v1/external_group`

Example request body:

{
  "group_name": "test1",
  "user_email": "@email.com"
}

Table 14. Request parameters

Request parameters	Description	Example format
`group_name`	The name of the group from which the user is to be removed.	"group_name": "test1"
`user_email`	The email of the user to be removed from the group.	"user_email": "username@email.com"

Example response and parameters

After you send the request, the endpoint responds with the following type of information:

{
    "status": "success"
}

Table 15. Query results and their description

Field	Type	Description
`status`	string	Indicates if the deletion was successful. If the user does not belong to the group, it is also treated as a successful deletion.