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

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

Return codes

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