Get groups

This method returns a list of all existing user groups.

The user running this Web service must have Audit users permissions.

Groups on the same level as your user or lower in the the Vault hierarchy are retrieved.

The groups that are returned depends on the HideVaultUsersTree parameter is defined in the dpbaram.ini file.
- If HideVaultUsersTree is set to No, all groups are returned (instead of only those on the same level or lower in the Vault hierarchy).
- If HideVaultUsersTree is set to Yes, only auditors and managers are allowed to get all groups.
Retrieving more than 1,000 groups may cause a slowdown in the response.

URL

https://<IIS_Server_Ip>/PasswordVault/api/UserGroups

Make sure there are no spaces in the URL.

The following characters are not supported in URL values: + & %

Resource information

HTTP method	Content type
GET	application/json

Header parameter

Parameter	Description
Authorization	The token that identifies the session, encoded in BASE 64. Type: String Mandatory: Yes Default value: None

Parameter

Description

Authorization

The token that identifies the session, encoded in BASE 64.

Type: String

Mandatory: Yes

Default value: None

URL parameters

Parameter	Description
filter	Filters according to the REST standard. Search for groups using the following filters: groupType eq <Directory\|Vault> groupName eq <GroupName> Type: String Default value: None (all groups are returned)
sort	Property or properties by which to sort returned users, followed by asc (default) or desc to control sort direction. Separate multiple properties with commas, up to a maximum of three properties. groupname directory location Type: String
search	Searches according to the REST standard (searching with "contains"). Search matches when all search terms appear in the group name. Type: String Default value: None (all groups are returned)
includeMembers	Whether or not to return members for each user group as part of the response. If not sent, the value will be False. Type: Boolean Default value: False

Example

In a search for domain groups that contain 'Fin' and 'Audit':

Before URL encoding:

/PasswordVault/api/UserGroups?filter=groupType eq Directory&search=Fin Audit

After URL encoding:

/PasswordVault/api/UserGroups?filter=groupType%20eq%20Directory&search=Fin%20Audit

Body parameters

None.

Result

A list of all groups will be returned. The following information should be returned for each group.

{
  "value": [
    {
      "id": 8,
      "groupType": "Vault",
      "members": [
        {
          "UserName": "Auditor",
          "id": 3
        }
      ],
      "groupName": "Auditors",
      "description": "Auditors group",
      "location": "\\"
    }
  ],
  "count": 1
}

Parameter	Description
id	The unique ID of the group. Type: Number
groupType	Whether this is a Vault group or Directory group. Type: String Valid values: Vault, Directory
groupName	The name of a group in the Vault. Type: String
description	The description of the group. Type: String
location	The location of the group in the Vault’s hierarchy. Type: String
directory	Displays the name of the LDAP external directory to which the external group belongs. This is relevant only for the Directory group type. Type String
dn	Displays the full LDAP DN of the user in the external directory to which the external user belongs. This is relevant only for the Directory group type. Type: String
members	A list of users that are members of the group. See Member parameters.

Member parameters

Parameter	Description
username	The name of the user. Type: String
id	The ID of the user. Type: Long

Parameter

Description

username

The name of the user.

Type: String

The ID of the user.

Type: Long

Return codes

For a complete list of return codes, see Return Codes.