Get discovered accounts

This method returns a list of all the discovered accounts from the Pending Accounts list. To run this web service, the user must be a member of the Vault admins group.

 

Discovered accounts that were onboarded either manually or automatically, according to predefined rules, won't be returned using this method.

 

URL

 
https://{PVWA_SERVER}/passwordvault/api/DiscoveredAccounts
 

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

The following (optional) parameters can be used in the query string in the URL.

Parameter

Description

filter

Search for accounts using filters (see Filter parameters for details):

  • platformType
  • privileged
  • accountEnabled

Type: string

Mandatory: no

Default value: none

Example: platformType eq Windows Server Local AND privileged eq true AND accountEnabled eq true

search

Searches according to the REST standard (search="search word"). Search is supported for userName and address.

Type: string

Mandatory: no

Default value: none

Example: search=admin

searchType

The type of search to perform. The keyword can either be contained within the account property values, or at the beginning of the value specified in the Search parameter. When using a keyword at the beginning of a value, performance is enhanced.

Type: string

Valid values: contains (default) or startswith

Mandatory: no

Default value: none

Example: searchtype=contains

offset

The offset of the first returned accounts into the list of results.

Type: integer

Mandatory: no

Default value: 0

limit

The maximum number of returned accounts. If not specified, the server limits the results to 100. The maximum number that can be specified is 1000.

Type: integer

Mandatory: no

Default value: 100

Filter parameters

 

To use more than one filter, you can use the AND operator.

For example, https://cyberark.com/PasswordVault/api/DiscoveredAccounts?filter=platformType eq Windows Server Local AND privileged eq true AND accountEnabled eq true

Parameter

Description

platformType

Whether to return only the accounts of a specific platform

Type: string

Valid values:

  • Windows Server Local
  • Windows Desktop Local
  • Windows Domain
  • Unix
  • Unix SSH Key
  • AWS
  • AWS Access Keys

Example: GET https://cyberark.com/PasswordVault/api/DiscoveredAccounts?filter=platformType eq Windows Server Local

privileged

Whether to return only privileged accounts or not

Type: boolean

Valid values: true/false

Example: https://cyberark.com/PasswordVault/api/DiscoveredAccounts?filter=privileged eq true

accountEnabled

Whether to return only enabled accounts or not

Type: boolean

Valid values: true/false

Example: https://cyberark.com/PasswordVault/api/DiscoveredAccounts?filter=accountEnabled eq true

Result

 
{
  "value": [
    {
      "id": "18_5",
      "name": "win8.example.com-administrator-e7626445-404b-4647-9b23-c4f08513a688",
      "userName": "administrator",
      "address": "win8.example.com",
      "accountEnabled": true,
      "osGroups": "Backup Operators,IIS_IUSRS,Network Configuration Operators",
      "platformType": "Windows Server Local",
      "domain": "example.com",
      "lastLogonDateTime": 1530635686,
      "lastPasswordSetDateTime": 1530635786,
      "passwordNeverExpires": false,
      "osVersion": "Windows Server 2012 R2 Standard",
      "privileged": false,
      "userDisplayName": "User Display Name",
      "description": "User Description",
      "passwordExpirationDateTime": 1530645686,
      "osFamily": "Server",
      "organizationalUnit": "CN=Users,DC=example,DC=com",
      "platformTypeAccountProperties": {
        "SID": "S-1-5-21-304654729-3147011263-1431158397-3154"
      },
      "additionalProperties": {
        "AccountType": "Local",
        "Port": 445,
        "UserDN": "CN=administrator,CN=Users,DC=example,DC=com",
        "CreationMethod": "WebService"
      },
      "numberOfDependencies": 2
    },
    {
      "id": "18_6",
      "name": "win10.example.com-administrator-e7626445-404b-4647-9b23-c4f08513a690",
      "userName": "administrator",
      "address": "win10.example.com",
      ...
    },
    {
      "id": "18_7",
      "name": "aws.com-amazon_accesskey_user-e7626445-404b-4647-9b23-c4f08513a850",
      "userName": "amazon_accesskey_user",
      "address": "aws.com",
      "discoveryDate": 1530635688,
      "platformType": "AWS Access Keys",
      "privileged": true,
      "platformTypeAccountProperties": {
        "awsAccessKeyID": "ASASASASSA",
        "awsAccountID": "123123123123"
      }
    },
    {
      "id": "18_8",
      "name": "aws.com-amazon_dashboard_user-e7626445-404b-4647-9b23-c4f08513a855",
      "userName": "amazon_dashboard_user",
      "address": "aws.com",
      "discoveryDate": 1530635655,
      "platformType": "AWS",
      "privileged": true,
      "platformTypeAccountProperties": {
        "awsAccountID": "123123123123"
      }
    },
    {
      ...
    }
  ],
  "count": 500,
  "nextLink": api/DiscoveredAccounts?search=administrator&offset=100
}

The response includes only the properties that exist for each discovered account. Non-existing properties or irrelevant properties that are not populated are omitted.

Parameter

Description

value

A list of pending discovered accounts.

Type: array

See Value parameters for each account.

count

The total number of results across all pages.

Type: integer

nextLink

An opaque URL to the next page of results. Should be present only when the requested page size (limit) is not specified, and there are more results than a single page, as defined by the server.

The last page shouldn't have 'nextLink' in the response.

If the limit in the request is too high, an error is returned.

Type: string

Value parameters for each account

Parameter

Description

id

The ID of the discovered account.

Type: string

Valid values: account id

name

The name of the account in the PasswordManager_Pending safe.

Type: string

Valid values: file name in the Safe

userName

The name of the discovered account user.

Type: string

address

The name or address of the machine\domain where the account was discovered.

Type: string

Valid values: machine name or address

discoveryDateTime

The date the account was discovered.

Type: integer

Valid values: Unix time

accountEnabled

The state of the account, defined in the discovery source.

Note: The state of domain accounts is based on the Active Directory. The state of local accounts is based on the local machine. If this parameter is not set, it is considered null.

Type: boolean

Valid values: true/false

osGroups

The group names that the account belongs to, such as Administrators or Operators.

Type: string

Valid values: group name

platformType

The platform where the discovered account is located.

Type: string

Valid values

  • Windows Server Local
  • Windows Desktop Local
  • Windows Domain
  • Unix
  • Unix SSH Key
  • AWS
  • AWS Access Keys

domain

The domain of the account.

Type: string

Valid values: domain name

lastLogonDateTime

The date this account was last logged into, defined in the discovery source.

Type: integer

Valid values: Unix time

lastPasswordSetDateTime

The date this password was last set, defined in the discovery source.

Type: integer

Valid values: Unix time

passwordNeverExpires

Whether or not this password expires, defined in the discovery source. If this parameter is not set, it is considered null.

Type: boolean

Valid values: true/false

osVersion

The version of the OS where the account was discovered.

Type: string

Valid values: operating system

privileged

Whether the discovered account is privileged or non-privileged. If this parameter is not set, it is considered null.

Type: boolean

Valid values: true/false

privilegedCriteria

The criteria that determines whether or not the discovered account is privileged. For example, the user or group name.

Type: string (separate multiple strings with a semicolon ";")

userDisplayName

The user's display name.

Type: string

Valid values: username

description

A description of the account, defined in the discovery source.

Type: string

passwordExpirationDateTime

The expiration date of the account, defined in the discovery source.

Type: integer

Valid values: Unix time

osFamily

The type of machine where the account was discovered. If this parameter is not set, it is considered null and will not be returned in the result.

Type: string

Valid values: workstation/server

organizationalUnit

The organizational unit where the account is defined.

Type: string

Valid values: organizational unit

additionalProperties

List of name=value pairs for additional properties of the account.

The list of properties is valid file properties in the Vault.

Type: list of name=value pairs

platformTypeAccountProperties

The object that contains the key-value pairs to associate with the account, as defined by the account platform type schema. Only properties that appear in the platform type schema are allowed.

Type: list of name=value pairs

Valid values: according to the platform type schema

numberOfDependencies

The number of dependencies for the discovered account.

Type: integer

Windows platform type account parameters

Parameter

Description

sid

The security ID. This parameter is only relevant for Windows accounts.

Type: string

Valid values: security ID

Unix platform type account parameters

Parameter

Description

uid

The unique user ID. This parameter is relevant only for Unix accounts.

Type: integer

Valid values: user ID

gid

The unique group ID. This parameter is relevant only for Unix accounts.

Type: integer

Valid values: group ID

Unix SSH Keys platform type account parameters

Parameter

Description

uid

The unique user ID. This parameter is only relevant for a Unix SSH Key.

Type: integer

Valid values: user ID

gid

The unique group ID. This parameter is only relevant for a Unix SSH Key.

Type: integer

Valid values: group ID

fingerprint

The fingerprint of the discovered SSH Key. The public and private keys of the same trust have the same fingerprint. This is relevant only for SSH Keys.

Type: string

size

The size in bits of the generated key. Optional values are 1024, 2048, 4096 and 8192. The default value is 2048.

Type: integer

path

The path of the public key on the target machine. The default value is ~/.ssh/authorized_keys.

Type: string

format

The format of the SSH Key.

Type: string

comment

Any text that was added when the key was created.

Type: string

encryption

The type of encryption used to generate the SSH Key. Optional values are RSA and DSA.

Type: string

AWS platform type account parameters

Parameter

Description

awsAccountID

The AWS account ID is a 12-digit number such as 123456789012 that you use to construct Amazon Resource Names (ARNs). When you refer to resources such as an IAM user or a Glacier vault, the account ID distinguishes your resources from resources in other AWS accounts.

Type: number

AWS access keys platform type account parameters

Parameter

Description

awsAccountID

The AWS account ID is a 12-digit number such as 123456789012 that you use to construct Amazon Resource Names (ARNs). When you refer to resources such as an IAM user or a Glacier vault, the account ID distinguishes your resources from resources in other AWS accounts.

Type: number

awsAccessKeyID

The Access Key ID that was used for programmatic authentication in the API call for the account.

Type: string

Return codes

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