Add discovered accounts

This method adds newly discovered accounts and their dependencies.

Make sure there are no spaces in the URL.

The following characters are not supported in URL values: + & %
If the URL includes a dot (.), add a forward slash (/) at the end of the URL. For example: api/Safes/MySafe/Members/user@cyber.com/

Action	Description
Discovered account	Discovered accounts are added to the Pending Accounts list.
Discovered dependency	Discovered dependencies are added to the Pending Accounts list or are automatically added to the corresponding master account that has already been onboarded.
Automatic onboarding	Discovered accounts are onboarded according to matching onboarding rules. If automatic onboarding fails for any reason, the account is added to the Pending Accounts list.

The user who runs this web service requires the following users and permissions:

To add pending accounts:

User: Owner of PasswordManager_Pending Safe
Permissions:
- Add account
- List files
- Update account properties

To onboard the account:

User: Owner of the target Safe of the onboarding rule.
Permissions:
- Add account
- Update account properties
- Initiate CPM account management operations

URL

https://<subdomain>.privilegecloud.cyberark.cloud/PasswordVault/API/DiscoveredAccounts/

Resource information

HTTP method	POST
Content type	application/json

Header parameter

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

Body parameters

Windows account

{

"userName":"user1",
"address":"win8.example.com",
"platformTypeAccountProperties":{"SID":"S-1-5-21-304654729-3147011263-1431158397-3154"},
"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",
"additionalProperties":{"Port":445,"UserDN":"CN=user1,CN=Users,DC=example,DC=com"},

"Dependencies": [ {

            "name": "ServiceDep",
            "address": "win8.example.com",
            "type": "Windows Service"

}]

}

AWS accounts

{
"userName":"amazon_accesskey_user",
"address":"aws.com",
"discoveryDate":"2018-05-03T13:00:00Z",
"platformType":"AWS Access Keys",
"privileged":true,

"platformTypeAccountProperties":{"awsAccessKeyID":"ASASASASSA","awsAccountID":"123123123123"}
}

{
"userName":"amazon_dashboard_user",
"address":"aws.com",
"discoveryDate":"2018-05-03T13:00:00Z",
"platformType":"AWS",
"privileged":true,

"platformTypeAccountProperties":{"awsAccountID":"123123123123"}
}

Azure account


{
"userName":string,
"address":string,
"discoveryDate":"1530635689",
"platformType":"Azure Password Management",
"accountEnabled":true,
"privileged":true,
"privilegedCriteria":string,
"platformTypeAccountProperties":{"activeDirectoryID":string}

}

Parameter

userName

Type

String

Description

The name of the account user.

Parameter

address

Type

String

Description

The name or address of the machine where the account is located.

Valid values

Machine name or address

Parameter

discoveryDateTime

Type

Int

Description

The date the account was discovered.

Default value

Current time

Valid values

Unix time

Parameter

accountEnabled

Type

Boolean

Description

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

Domain accounts are discovered in the Active Directory. Local accounts are discovered on machines. If this parameter is not set, it is considered null.

Valid values

True / False

Parameter

osGroups

Type

String

Description

The name of the group the account belongs to, such as Administrators or Operators.

Valid values

Group name

Parameter

platformType

Type

String

Description

The platform where the discovered account is located.

Valid values

One of the following:

Windows Server Local
Windows Desktop Local
Windows Domain
Unix
Unix SSH Key
AWS
AWS Access Keys
Azure Password Management

Parameter

domain

Type

String

Description

The domain of the account.

Valid values

Domain name

Parameter

lastLogonDateTime

Type

Int

Description

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

Valid values

Unix time

Parameter

lastPasswordSetDateTime

Type

Int

Description

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

Valid values

Unix time

Parameter

passwordNeverExpires

Type

Boolean

Description

Whether or not this password expires, defined in the discovery source.

If this parameter is not set, it is considered null.

This attribute cannot be set if passwordExpirationDateTime is specified.

Valid values

True / False

Parameter

osVersion

Type

String

Description

The version of the OS where the account was discovered.

Valid values

Operating system

Parameter

privileged

Type

Enum

Description

Whether the discovered account is privileged or non-privileged.

If this parameter is not set, it is considered null.

Valid values

Privileged / Non-privileged

Parameter

privilegedCriteria

Type

String

Description

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

Valid values

String. Separate multiple strings with ";".

Parameter

userDisplayName

Type

String

Description

The user's display name.

Valid values

Username

Parameter

description

Type

String

Description

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

Parameter

passwordExpirationDateTime

Type

Int

Description

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

Valid values

Unix time

Parameter

osFamily

Type

String

Description

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.

Valid values

Workstation/Server

Parameter

additionalProperties

Type

List of name=value pairs

Description

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

This is an open list that is not validated.

The list of properties should be valid file properties in the Vault.

Parameter

organizationalUnit

Type

String

Description

The organizational unit where the account is defined.

Valid values

Parameter

platformTypeAccountProperties

Type

Int

Description

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

Mandatory

For UnixSSHKey, AWS, and AWS Access Keys

Valid values

According to the platform type schema

Windows

Parameter	SID
Type	String
Description	Security ID. This parameter is relevant only for Windows accounts.
Valid values	Security ID

Unix

Parameter	uid
Type	String
Description	The unique user ID. This parameter is relevant only for Unix accounts.
Valid values	User ID
Parameter	gid
Type	String
Description	The unique group ID. This parameter is relevant only for Unix accounts.
Valid values	Group ID

Unix SSH Keys

Parameter	uid
Type	String
Description	The unique user ID. This parameter is relevant only for Unix SSH Key.
Valid values	User ID
Parameter	gid
Type	String
Description	The unique group ID. This parameter is relevant only for Unix SSH Key.
Valid values	Group ID
Parameter	fingerprint
Type	String
Description	The fingerprint of the discovered SSH key. The public and private keys of the same trust have the same fingerprint. This is relevant for SSH keys only.
Mandatory	Yes (for SSH Keys)
Parameter	size
Type	Int
Description	The size in bits of the generated key.
Valid values	1024, 2048, 4096 and 8192
Default value	2048
Parameter	path
Type	String
Description	The path of the public key on the target machine.
Default value	~/.ssh/authorized_keys
Parameter	format
Type	String
Description	The format of the private SSH key.
Parameter	comment
Type	String
Description	Any text added when the key was created.
Parameter	encryption
Type	String
Description	The type of encryption used to generate the SSH key.
Valid values	Optional values are RSA and DSA.

AWS

Parameter	awsAccountID
Type	String
Description	The account ID on the AWS console. This is a 12-digit number, such as 123456789012, used to construct Amazon Resource Names (ARNs). When referring to resources, such as an IAM user or a Glacier vault, the account ID distinguishes these resources from those in other AWS accounts.
Valid values	A 12-digit number

AWS Access Keys

Parameter	awsAccountID
Type	String
Description	The unique AWS account ID. This is a 12-digit number, such as 123456789012, used to construct Amazon Resource Names (ARNs). When referring to resources, such as an IAM user or a Glacier vault, the account ID distinguishes these resources from those in other AWS accounts.
Valid values	A 12-digit number
Parameter	awsAccessKeyID
Type	String
Description	The Access Key ID that was used for programmatic authentication in the API call for the account.
Valid values	AWS Access Key ID string

Azure Password Management

Parameter	activeDirectoryID
Type	String
Description	The Azure Active Directory tenant ID
Valid values

Dependencies

Parameter	name
Type	String
Description	The name of the dependency.
Valid values
Parameter	address (mandatory)
Type	String
Description	The address of the dependency.
Valid values	IP address or DNS hostname
Parameter	type (mandatory)
Type	String
Description	The type of the dependency.
Valid values	COM+ Application IIS Anonymous Authentication IIS Application Pool Windows Scheduled Task Windows Service
Parameter	taskFolder
Type	String
Description	The dependency task folder. This is relevant for Windows Scheduled Tasks.
Valid values

Result

Windows account

{
          id: 19_5,
          status: addedAccount/addedAsPending/
updatedAccount/updatedPending/
alreadyExist,
            name: user1,
            address: win8.example.com,
            safe: PasswordManager_Pending,
            dependencies:[ {
                        id: 19_6,
                        status: addedDependency/addedAsPending/
alreadyExist/failed/skip,
                        type: Windows Service,
                        name: ServiceDep,
                        address: win8.example.com,
                        failureReason: ""
}, {…}]
}

Parameter	id
Type	Number
Description	The ID of the onboarded or pending account.
Valid values	Valid account ID
Parameter	status
Type	Enum
Description	The status of the account.
Valid values	Possible values are: addedAccount: The account was onboarded to the Vault addedAsPending: The account was added to the Pending Accounts list. updatedAccount: The account already exists and was updated, if needed. updatedPending: The pending account already exists and was updated, if needed. alreadyExist: The account already exists and no new dependencies were added.
Dependencies
Parameter	id
Description	The ID of the onboarded or pending dependency.
Valid values	Number
Parameter	status
Description	The status of the dependency. Possible values are: addedDependency - The dependency was onboarded to the Vault. addedAsPending - The dependency was added to the Pending Accounts list. alreadyExist - The dependency already exists. failed - The system failed to add the dependency. skip - The dependency was not added because the previous dependency could not be added.
Valid values	Enum
Parameter	type
Description	The dependency type.
Valid values	String
Parameter	name
Description	The dependency name.
Valid values	String
Parameter	address
Description	The dependency address.
Valid values	String
Parameter	failureReason
Description	The reason why onboarding failed. This is only relevant if the status indicates that onboarding failed.
Valid values	String

Return codes

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