Add Safe

This method adds a new Safe to Privilege Cloud.

The user who runs this web service must have Add Safes permissions in Privilege Cloud.

Select the method that you want to use:

2nd gen API (recommended)

URL

https://<subdomain>.privilegecloud.cyberark.com/PasswordVault/API/Safes/

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/

Resource information

HTTP method	Content type
POST	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

{

  "numberOfDaysRetention": 7,

  "numberOfVersionsRetention": null,

  "oLACEnabled": true,

  "autoPurgeEnabled": true,

  "managingCPM": "passwordManager",

  "safeName": "PasswordManagerSafe",

  "description": "This is PasswordManager safe.",

  "location": ""

}

Parameter	Description
safeName	The unique name of the Safe. The following characters cannot be used in the Safe name: \ / : * < > . \| ? “% & + Type: String Mandatory: Yes Default value: None
description	The description of the Safe. Type: String Mandatory: No Default value: None
location	The location of the Safe in the Vault. Type: String Mandatory: No Default value: \\
olacEnabled	Whether or not to enable Object Level Access Control for the new Safe. Type: Boolean Mandatory: No Default value: No This option is not supported in Privilege Cloud.
managingCPM	The name of the CPM user who will manage the new Safe. Type: String Mandatory: No Default value: None
numberOfVersionsRetention	The number of retained versions of every password that is stored in the Safe. Type: Number Mandatory: No Default value: None If you select this option, the other Version management option, numberOfDaysRetention, is not available.
numberOfDaysRetention	The number of days that password versions are saved in the Safe. Type: Number Mandatory: No Default value: 7 If you select this option, the other Version management option, numberOfVersionsRetention, is not available.
AutoPurgeEnabled	Whether or not to automatically purge files after the end of the Object History Retention Period defined in the Safe properties. Report Safes and PSM Recording Safes are created automatically with AutoPurgeEnabled set to Yes. These Safes cannot be managed by the CPM. Type: Boolean Mandatory: No Default value: No

Result

{

    "safeUrlId": "PasswordManagerSafe",

    "safeName": "PasswordManagerSafe",

    "safeNumber": 21,

    "description": "This is PasswordManager safe.",

    "location": "\\",

    "creator": {

        "id": "14",

        "name": "AdminUser1"

    },

    "olacEnabled": true,

    "managingCPM": "PasswordManager",

    "numberOfVersionsRetention": null,

    "numberOfDaysRetention": 7,

    "autoPurgeEnabled": false,

    "creationTime": "1604919933",

    "lastModificationTime": 1604919933475657

}

Parameter	Description
safeUrlId	The unique ID of the Safe used when calling Safe APIs. Type: String
safeName	The name of the Safe. Type: String
safeNumber	The unique numerical ID of the Safe. Type: Integer
description	The description of the Safe. Type: String
location	The location of the Safe in the Vault. Type: String
creator	Contains the following parameters: creator.id: The ID of the user that created the Safe. Type: String creator.name: The name of the user that created the Safe. Type: String
olacEnabled	Whether or not to enable Object Level Access Control for the new Safe. Type: Boolean This option is not supported in Privilege Cloud.
managingCPM	The name of the CPM user who will manage the new Safe. Type: String
numberOfVersionsRetention	The number of retained versions of every password that is stored in the Safe. Type: Number If you selected the other Version management parameter, numberOfDaysRetention, this parameter will return a NULL value.
numberOfDaysRetention	The number of days that password versions are saved in the Safe. Type: Number If you selected the other Version management parameter, numberOfVersionsRetention, this parameter will return a NULL value.
AutoPurgeEnabled	Whether or not to automatically purge files after the end of the Object History Retention Period defined in the Safe properties. Report Safes and PSM Recording Safes are created automatically with AutoPurgeEnabled set to Yes. In addition, these Safes cannot be managed by the CPM. Type: Boolean
creationTime	The Unix creation time of the Safe. Type: DateTime
lastModificationTime	The Unix time when the Safe was last updated. Type: DateTime

1st gen API

URL

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/

https://<subdomain>.privilegecloud.cyberark.com/PasswordVault/WebServices/PIMServices.svc/Safes

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

{
"safe":{
"SafeName":"<Safe name>",
"Description":"<Description>",
"OLACEnabled":<true/false>,
"ManagingCPM":"<CPM user>",
"NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>
  }
}

Parameter	Description
SafeName	Name of a Safe to create. Specify up to 28 characters. The following characters aren’t allowed: \/:*<>".\| Do not start a Safe name with a space. Mandatory: Yes Type: String Valid values: New Safe name
Description	Description of the new Safe Type: String Valid values: Up to 100 characters.
OLACEnabled	Whether or not to enable Object Level Access Control for the new Safe. Type: Boolean Valid values: True/False This option is not supported in Privilege Cloud.
ManagingCPM	The name of the CPM user who will manage the new Safe.. Type: String Valid values: An existing CPM user or "" to prevent the CPM from managing the Safe.
NumberOfVersionsRetention	The number of retained versions of every password that is stored in the Safe. Specify either this parameter or NumberOfDaysRetention. If you specify this parameter the NumberOfDaysRetention parameter is disabled. Type: Numeric Valid values: 1-999
NumberOfDaysRetention	The number of days for which password versions are saved in the Safe. Specify either this parameter or NumberOfVersionsRetention If you specify this parameter the NumberOfVersionsRetention parameter is disabled. Type: Numeric Valid values: 1-3650

Result

{
"safe":{
    "SafeName":"<The name of the new Safe>",
    "Description":"<Description for the new Safe>",
    "OLACEnabled":<true/false>,
    "ManagingCPM":"<Name of CPM user managing the Safe>",
    "NumberOfVersionsRetention":<1-999>,
    "NumberOfDaysRetention":<1-3650>
  }
}

Return codes

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