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

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`

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

{
  "data": [
    {
      "created_at": null,
      "last_modified": null,
      "group_id": 123,
      "group_name": "test1"
    },
    {
      "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	Subfield	Type	Description
`data`		array	The details of each group
`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. A subfield of `meta`.

Listing all members in a group

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

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`

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

[
    {
        "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.

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`

The request body is sent in the following format:

{
  "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:

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

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.

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

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

[
{
  "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.

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`

The request body is sent in the following format:

{
  "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"

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.