Get groups

This method returns a list of all existing user groups.

The user performing this task:

  • Must have Audit users permissions in the Safe.

  • Can see groups either only on the same level, or lower in the Vault hierarchy.

    This depends on the HideVaultUsersTree parameter defined in the dbparam.ini. If HideVaultUsersTree is set to No, all groups will be returned (not only those in the same level or lower in the Vault hierarchy). If this parameter is set to Yes, only auditors and managers will be allowed to get all groups.
 
  • Filtering for this task is supported only from Vault v10.5.

  • Retrieving more than 1,000 groups may cause a slowdown in 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.

Type: String (Boolean expression)

Default value: None

Valid values (supported filters include): groupType eq <Directory|Vault>

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)

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.