Password Safe APIs

Password Safe APIs require a valid Password Safe license.

This document specifies the Representational State Transfer (REST) compliant Application Programmer Interface (API) over HTTPS for BeyondInsight and Password Safe. It is a way to integrate a portion of the BeyondInsight and Password Safe functionality into your own applications.

Using the REST API makes it easier for users to build customized solutions for their specific needs while ensuring secure data transmission. The API provides a set of predefined operations, or endpoints, that can be accessed using HTTP Requests, including GET requests to retrieve data, POST requests to create new data, PUT requests to update existing data, and DELETE requests to remove data.

This resource is intended for readers with knowledge of HTTPS request and response processing, web development, and JSON notation.

Access policies

GET AccessPolicies

Purpose

Returns a list of Password Safe access policies.

Required permissions

Password Safe Role Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        AccessPolicyID:int,
        Name:string,
        Description:string,
        Schedules :
        [
            {
                ScheduleID : int,
                RequireReason : bool,
                RequireTicketSystem : bool,
                TicketSystemID : short?,
                AccessTypes :
                [
                    {
                        AccessType : string,
                        IsSession : bool,
                        RecordSession : bool,
                        MinApprovers : int,
                        MaxConcurrent : int
                    },
                    …
                ]
            },
            …
        ]
    },
    …
]

Response codes

200 - Request successful. Access policies in response body.

POST AccessPolicies/Test

Purpose

Tests access to a managed account and returns a list of Password Safe access policies that are available in the request window.

Required roles

Requestor role.

Request body

Content-Type: application/json

{
    SystemId: int, 
    AccountId: int, 
    DurationMinutes : int
}

Response body

Content-Type: application/json

[
    {
        AccessPolicyID:int,
        Name:string,
        Description:string,
        Schedules :
        [
            {
                ScheduleID : int,
                RequireReason : bool,
                RequireTicketSystem : bool,
                TicketSystemID : short?,
                AccessTypes :
                [
                    {
                        AccessType : string,
                        IsSession : bool,
                        RecordSession : bool,
                        MinApprovers : int,
                        MaxConcurrent : int
                    },
                    …
                ]
            },
            …
        ]
    },
    …
]

Response codes

• 200 - Request successful. Access policies in response body.
• 403 - User does not have permissions to request the indicated account or the account does not have API access enabled. Response body contains a status code indicating the reason for this forbidden access:
  • 4031 - User does not have permission to request the account or the account is not valid for the system.

Aliases

GET Aliases

Purpose

Returns a list of requestable managed account aliases.

Required roles

Requestor or Requestor/Approver role for the preferred managed account referenced by the alias.

Query parameters

• state (optional, default: 1, 2): Zero or more state values, i.e., 'state=2', 'state=1,2', 'state=0,1,2'.
  • 0: Unmapped
  • 1: Mapped
  • 2: Highly Available

ℹ️

Note

Only Aliases with a mapped state of 1 or 2 can be used for API POST Aliases/{id}/Requests.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AliasId: int,
        AliasName: string,
        AliasState: int,
        SystemId: int,
        SystemName: string,
        AccountId: int,
        AccountName: string,
        DomainName: string,
        InstanceName: string,
        DefaultReleaseDuration: int,
        MaximumReleaseDuration: int,
        LastChangeDate: datetime,
        NextChangeDate: datetime,
        IsChanging: bool,
        ChangeState: int,

        MappedAccounts :
        [
            {
                AliasID: int,
                ManagedSystemID: int,
                ManagedAccountID: int,
                Status: string
            },
            …
        ]
    }
    …
]

Response codes

200 - Request successful. Aliases in response body.

GET Aliases/{id}

Purpose

Returns a requestable managed account alias by ID.

Required roles

Requestor or Requestor/Approver role for the preferred managed account referenced by the alias.

URL parameters

id: ID of the managed account alias.

Request body

None.

Response body

Content-Type: application/json

{
    AliasId: int,
    AliasName: string,
    AliasState: int,
    SystemId: int,
    SystemName: string,
    AccountId: int,
    AccountName: string,
    DomainName: string,
    InstanceName: string,
    DefaultReleaseDuration: int,
    MaximumReleaseDuration: int,
    LastChangeDate: datetime,
    NextChangeDate: datetime,
    IsChanging: bool,
    ChangeState: int,

    MappedAccounts :
    [
        {
            AliasID: int,
            ManagedSystemID: int,
            ManagedAccountID: int,
            Status: string
        },
        …
    ]
}

Response codes

200 - Request successful. Alias in response body.

GET Aliases?name={name}

Purpose

Returns a requestable managed account alias by name.

Required roles

Requestor or Requestor/Approver role for the preferred managed account referenced by the alias.

URL parameters

name: Name of the managed account alias.

Request body

None.

Response body

Content-Type: application/json

{
    AliasId: int,
    AliasName: string,
    AliasState: int,
    SystemId: int,
    SystemName: string,
    AccountId: int,
    AccountName: string,
    DomainName: string,
    InstanceName: string,
    DefaultReleaseDuration: int,
    MaximumReleaseDuration: int,
    LastChangeDate: datetime,
    NextChangeDate: datetime,
    IsChanging: bool,
    ChangeState: int,

    MappedAccounts :
    [
        {
            AliasID: int,
            ManagedSystemID: int,
            ManagedAccountID: int,
            Status: string
        },
        …
    ]
}

Response codes

200 - Request successful. Alias in response body.

Applications

GET Applications

Purpose

Returns a list of applications.

Required permissions

Password Safe Account Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        ApplicationID : int,
        Name : string,
        DisplayName : string,
        Version : string,
        Command : string,
        Parameters : string,
        Publisher : string,
        ApplicationType : string,
        FunctionalAccountID : int, // can be null
        ManagedSystemID : int, // can be null
        IsActive : bool,
     SmartRuleID : int // can be null
    }
    …
]

Response codes

200 - Request successful. Applications in response body.

GET Applications/{id}

Purpose

Returns an application by ID.

Required permissions

Password Safe Account Management (Read).

URL parameters

id: ID of the application.

Request body

None.

Response body

Content-Type: application/json

{
    ApplicationID : int,
    Name : string,
    DisplayName : string,
    Version : string,
    Command : string,
    Parameters : string,
    Publisher : string,
    ApplicationType : string,
    FunctionalAccountID : int, // can be null
    ManagedSystemID : int, // can be null
    IsActive : bool,
    SmartRuleID : int // can be null        
}

Response codes

200 - Request successful. Application in response body.

Attributes

GET ManagedAccounts/{managedAccountID}/Attributes

Purpose

Returns a list of attributes by managed account ID.

Required permissions

Password Safe Account Management (Read), Attribute Management (Read).

URL parameters

managedAccountID: ID of the managed account.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AttributeID : int,
        AttributeTypeID : int,
        ParentAttributeID : int, // can be null 
        ShortName : string,
        LongName : string, 
        Description : string, ValueInt : int, // can be null 
        IsReadOnly: bool
    },
    …
]

Response codes

201 - Request successful. Attributes associated with the asset in the response body.

GET ManagedSystems/{managedSystemID}/Attributes

Purpose

Returns a list of attributes by managed system ID.

Required permissions

Password Safe System Management (Read), Attribute Management (Read).

URL parameters

managedSystemID: ID of the managed system.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AttributeID : int,
        AttributeTypeID : int,
        ParentAttributeID : int, // can be null
        ShortName : string,
        LongName : string,
        Description : string,
        ValueInt : int, // can be null
        IsReadOnly: bool
    },
…
]

Response codes

200 - Request successful. Attributes associated with the Managed System in the response body.

POST ManagedAccounts/{managedAccountID}/Attributes/{attributeID}

Purpose

Assigns an attribute to a managed account.

Required permissions

Password Safe Account Management (Read/Write), Attribute Management (Read/Write).

URL parameters

• managedAccountID: ID of the managed account.
• attributeID: ID of the attribute.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AttributeID : int,
        AttributeTypeID : int,
        ParentAttributeID : int, // can be null 
        ShortName : string,
        LongName : string, 
        Description : string, ValueInt : int, // can be null 
        IsReadOnly: bool
    },
    …
]

Response codes

201 - Request successful. Attribute in the response body.

POST ManagedSystems/{managedSystemID}/Attributes/{attributeID}

Purpose

Assigns an attribute to a managed system.

Required permissions

Password Safe System Management (Read/Write), Attribute Management (Read/Write).

URL parameters

managedSystemID: ID of the managed system.

attributeID: ID of the attribute.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AttributeID : int,
        AttributeTypeID : int,
        ParentAttributeID : int, // can be null
        ShortName : string,
        LongName : string,
        Description : string,
        ValueInt : int, // can be null
        IsReadOnly: bool
    },
    …
]

Response codes

201 - Request successful. Attribute in the response body.

DELETE ManagedAccounts/{managedAccountID}/Attributes

Purpose

Deletes all managed account attributes by managed account ID.

Required permissions

Password Safe Account Management (Read/Write), Attribute Management (Read/Write).

URL parameters

managedAccountID: ID of the managed account.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedAccounts/{managedAccountID}/Attributes/{attributeID}

Purpose

Deletes a managed account attribute by managed account ID and attribute ID.

Required permissions

Password Safe Account Management (Read/Write), Attribute Management (Read/Write).

URL parameters

• managedAccountID: ID of the managed account.
• attributeID: ID of the attribute.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedSystems/{managedSystemID}/Attributes

Purpose

Deletes all managed system attributes by managed system ID.

Required permissions

Password Safe System Management (Read/Write), Attribute Management (Read/Write).

URL parameters

managedSystemID: ID of the managed system.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedSystems/{managedSystemID}/Attributes/{attributeID}

Purpose

Deletes a managed system attribute by managed system ID and attribute ID.

Required permissions

Password Safe System Management (Read/Write), Attribute Management (Read/Write).

URL parameters

managedSystemID: ID of the managed system.

attributeID: ID of the attribute.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

Configuration

GET Configuration/Version

Purpose

Returns the current system version.

Request body

None.

Response body

Content-Type: application/json

{
    Version : string
}

Response codes

200 – Request successful. Version model in the response body.

Credentials

GET Credentials/{requestId}

Purpose

Retrieves the credentials for an approved and active (not expired) credentials release request.

Required permissions

None.

URL parameters

requestId: ID of the request for which to retrieve the credentials.

Query parameters

• type: (optional, default: password) Type of credentials to retrieve.
  • password: Returns the password in the response body.
  • dsskey: Returns the DSS private key in the response body.

ℹ️

Note

The key is returned in the state in which it was set. For example, an encrypted key is returned encrypted.

• passphrase: Returns the DSS key passphrase in the response body.

ℹ️

Note

passphrase supported only for encrypted DSS keys.

Request body

None.

Response body

Credentials: string

Response codes

• 200 - Request successful. Credentials in the response body.
• 403 - User does not have permissions to request credentials for the indicated account or the account does not have API access enabled.
  • 4031 - User does not have permission to request credentials. 4034 - Request is not yet approved.
• 404 - Could not find the request to release. The specified request ID may have already been released or has expired.

GET Aliases/{aliasId}/Credentials/{requestId}

Purpose

Retrieves the credentials and alias details for an approved and active (not expired) credentials release request for an alias.

Required permissions

None.

URL parameters

• aliasId: ID of the alias.
• requestId: ID of the request for which to retrieve the credentials.

Query parameters

• type: (optional, default: password) Type of credentials to retrieve.
• password: Returns the password in response body property Password.
• dsskey: Returns the DSS private key in response body property PrivateKey.

ℹ️

Note

The key is returned in the state in which it was set. For example, an encrypted key is returned encrypted.

• passphrase: returns the DSS key passphrase in response body property Passphrase.

ℹ️

Note

passphrase supported only for encrypted DSS keys.

Request body

None.

Response body

Content-Type: application/json

{
            AliasID: int,
            AliasName: string,
            SystemID: int,
            SystemName: string,
            AccountID: int,
            AccountName: string,
            DomainName: string,
            Password: string,
            PrivateKey: string,
            Passphrase: string
        }

Response codes

• 200 - Request successful. Account details and credentials in the response body.
• 403 - User does not have permissions to request credentials for the indicated alias or the account referenced by the alias does not have API access enabled.
  • 4031 - User does not have permission to request credentials.
  • 4034 - Request is not yet approved.
• 404 - Could not find the request to release. The specified request ID may have already been released or has expired.

Custom platforms

Administrators have the ability to to export the custom platform configuration data from a customer's on-premises Password Safe instance and import the configuration data into a Password Safe Cloud instance.

GET CustomPlatforms

Purpose

Returns a list of platforms for managed systems.

Required permissions

Password Safe Configuration Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        PlatformID : int,
        Name : string
    },
    …
]

Response body details

• PlatformID: Platform ID.
• Name: Platform Name.

Response codes

200 – Request successful.

GET CustomPlatforms/{id}

Purpose

Returns a custom platform by ID.

Required permissions

Password Safe Configuration Management (Read).

URL parameters

id: ID of the platform.

Request body

None.

Response body

Content-Type: application/json

[
    {
        PlatformID : int,
        Name : string
    },
    …
]

Response body details

• PlatformID: Platform ID.
• Name: Platform Name.

Response codes

200 – Request successful.

POST CustomPlatforms/Import

Purpose

Imports a custom platform.

Required permissions

Password Safe Configuration Management (Read/Write).

URL parameters

None.

Request body

{

    CustomPlatform : string

    
}

Response body

Content-Type: application/json

[
    {
    PlatformId : int,
       
    },
    …
]

Response body details

• PlatformId: The ID of the custom platform.

Response codes

200 – Request successful.

POST CustomPlatforms/{id}/Export

Purpose

Exports a particular custom platform.

Required permissions

Password Safe Configuration Management (Read).

URL parameters

id: ID of the custom platform.

Request body

None.

Response body

Content-Type: application/xml

Response body details

The custom platform XML data is returned in the response..

Response codes

200 – Request successful.

Managed account credentials

PUT Workgroups/{workgroupName}/Assets/{assetName}/ManagedSystems/ManagedAccounts/{accountName}/Credentials

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use PUT Credentials?workgroupName={workgroupName}&assetName={assetName}&accountName={accountName} instead.

Purpose

Updates the credentials for a managed account by Workgroup name, asset name, and managed account name, optionally applying the change to the managed system.

Required permissions

One of the following is required:

• Password Safe Account Management (Read/Write)
• ISA Role or Credentials Manager Role on a Smart Rule referencing the account

URL parameters

• workgroupName: Name of the Workgroup.
• assetName: Name of the asset.
• accountName: Name of the managed account for which to set the credentials.

Request body

Content-Type: application/json

{
    Password: string,
    PublicKey: string,
    PrivateKey: string,
    Passphrase: string,
    UpdateSystem: bool
}

Request body details

• Password: (optional) The new password to set. If not given, generates a new random password.
• PublicKey: (required if PrivateKey is given and updateSystem=true) The new public key to set on the host.
• PrivateKey: The private key to set (provide passphrase if encrypted).
• Passphrase: (optional) The passphrase to use for an encrypted private key.
• UpdateSystem: (default: true) Whether to update the credentials on the referenced system.

Response body

None.

Response codes

204 - Request Successful. No Response Body.

Directories

GET Directories

Purpose

Returns a list of directories.

Required permissions

One of: Password Safe System Management (Read), Password Safe Domain Management (Read).

Request body

None.

Response body

Content-type: application/json [ 
    {
        DirectoryID : int, 
        WorkgroupID : int, 
        PlatformID : int, 
        DomainName : string, 
        ForestName : string, 
        NetBiosName : string, 
        UseSSL : bool, 
        Port : int, // can be null 
        Timeout : short, 
        Description : string, 
        ContactEmail : string, 
        PasswordRuleID : int, 
        ReleaseDuration : int, 
        MaxReleaseDuration : int, 
        ISAReleaseDuration : int, 
        AccountNameFormat : int, 
        AutoManagementFlag : bool, 
        FunctionalAccountID : int, // can be null 
        CheckPasswordFlag : bool, 
        ChangePasswordAfterAnyReleaseFlag : bool, 
        ResetPasswordOnMismatchFlag : bool, 
        ChangeFrequencyType : string, 
        ChangeFrequencyDays : int,
    }
]

Response codes

200 - Request successful. Directory in response body.

GET Directories/{id}

Purpose

Returns a directory by ID.

Required permissions

One of: Password Safe System Management (Read), Password Safe Domain Management (Read).

URL parameters

id: ID of the directory.

Request body

None.

Response body

Content-Type: application/json

{
    DirectoryID : int,
    WorkgroupID : int,
    PlatformID : int,
    DomainName : string,
    ForestName : string,
    NetBiosName : string,
    UseSSL : bool,
    Port : int, // can be null
    Timeout : short,
    Description : string,
    ContactEmail : string,
    PasswordRuleID : int,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AccountNameFormat : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
}

POST Workgroups/{id}/Directories

Purpose

Creates a new directory in the Workgroup referenced by ID.

Required permissions

One of: Password Safe System Management (Read/Write), Password Safe Domain Management (Read/Write).

URL parameters

id: ID of the Workgroup.

Request body

Content-Type: application/json

{
    PlatformID : int,
    DomainName : string,
    ForestName : string,
    NetBiosName : string,
    UseSSL : bool,
    Port : int, // can be null
    Timeout : short,
    Description : string,
    ContactEmail : string,
    PasswordRuleID : int,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AccountNameFormat : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
}

Request body details

• PlatformID: (required) ID of the platform
• DomainName: (required) Name of the domain. Max string length is 128.
• ForestName: (required for Active Directory only, not applicable to LDAP) Name of the directory forest. Max string length is 64.
• NetBiosName: (required for Active Directory, optional for LDAP) NetBIOS name of the directory. Max string length is 15.
• UseSSL: (default: false) True to use an SSL connection, otherwise false.
• Port: (set automatically for Active Directory, optional for LDAP) The port used to connect to the host. If null and the related Platform is LDAP, Password Safe uses Platform.DefaultPort.
• Timeout: (seconds, default: 30) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• Description: (optional) Description of the directory. Max string length is 255.
• ContactEmail: Max string length is 1000.
• PasswordRuleID: (default: 0) ID of the default password rule assigned to managed accounts created under this managed system.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• AccountNameFormat: (Active Directory only, default: 0) Account Name format to use:
  • 0: Domain and Account. Use ManagedAccount.DomainName\ManagedAccount.AccountName
  • 1: UPN. Use the Managed Account UPN
  • 2: SAM. Use the Managed Account SAM Account Name
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false. Can be set if Platform.AutoManagementFlag is true.
  • FunctionalAccountID: (required if AutoManagementFlag is true) ID of the functional account used for managed account password changes. FunctionalAccount.PlatformID must match the PlatformID.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: (default: first) The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month
    • last: Changes scheduled for the last day of the month
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays)
  • ChangeFrequencyDays: (days: 1-999, required if ChangeFrequencyType is xdays) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59, default: 23:30) UTC time of day scheduled password changes take place.

Response body

Content-Type: application/json

{
    DirectoryID : int,
    WorkgroupID : int,
    PlatformID : int,
    DomainName : string,
    ForestName : string,
    NetBiosName : string,
    UseSSL : bool,
    Port : int, // can be null
    Timeout : short,
    Description : string,
    ContactEmail : string,
    PasswordRuleID : int,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AccountNameFormat : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
}

Response codes

201 - Request successful. Directory in response body.

PUT Directories/{id}

Purpose

Updates an existing directory by ID.

Required permissions

One of: Password Safe System Management (Read/Write), Password Safe Domain Management (Read/Write).

URL parameters

id: ID of the directory.

Request body

Content-Type: application/json

{
    PlatformID : int,
    WorkgroupID : int,
    DomainName : string,
    ForestName : string,
    NetBiosName : string,
    UseSSL : bool,
    Port : int, // can be null
    Timeout : short,
    Description : string,
    ContactEmail : string,
    PasswordRuleID : int,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AccountNameFormat : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
}

Request body details

• WorkgroupID: (required) ID of the Workgroup.
• PlatformID: (required) ID of the platform.
• DomainName: (required) Name of the domain. Max string length is 128.
• ForestName: (required for Active Directory only, not applicable to LDAP) Name of the directory forest. Max string length is 64..
• NetBiosName: (required for Active Directory, optional for LDAP) NetBIOS Name of the directory. Max string length is 15.
• UseSSL: (default: false) True to use an SSL connection, otherwise false.
• Port: (set automatically for Active Directory, optional for LDAP) The port used to connect to the host. If null and the related Platform is LDAP, Password Safe uses Platform.DefaultPort.
• Timeout: (seconds, default: 30) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• Description: (optional) Description of the directory. Max string length is 255.
• ContactEmail: Max string length is 1000.
• PasswordRuleID: (default: 0) ID of the default password rule assigned to managed accounts created under this managed system.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• AccountNameFormat: (Active Directory only, default: 0) Account name format to use:
  • 0: Domain and Account. Use ManagedAccount.DomainName\ManagedAccount.AccountName
  • 1: UPN. Use the Managed Account UPN
  • 2: SAM. Use the Managed Account SAM Account Name
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false. Can be set if Platform.AutoManagementFlag is true.
  • FunctionalAccountID: (required if AutoManagementFlag is true) ID of the functional account used for managed account password changes. FunctionalAccount.PlatformID must match the PlatformID.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: (default: first) The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month
    • last: Changes scheduled for the last day of the month
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays)
  • ChangeFrequencyDays: (days: 1-999, required if ChangeFrequencyType is xdays) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59, default: 23:30) UTC time of day scheduled password changes take place.

Response body

Content-Type: application/json

{
    DirectoryID : int,
    WorkgroupID : int,
    PlatformID : int,
    DomainName : string,
    ForestName : string,
    NetBiosName : string,
    UseSSL : bool,
    Port : int, // can be null
    Timeout : short,
    Description : string,
    ContactEmail : string,
    PasswordRuleID : int,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AccountNameFormat : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
}

Response codes

200 - Request successful. Directory in response body.

DELETE Directories

Purpose

Deletes a directory by ID.

Required permissions

One of: Password Safe System Management (Read/Write), Password Safe Domain Management (Read/Write).

URL parameters

id: ID of the directory.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Oracle internet directories

GET OracleInternetDirectories

Purpose

Returns a list of Oracle Internet Directories.

Required permissions

Password Safe System Management (Read).

Request body

None.

Response body

Content-type: application/json

[{
    OrganizationID : Guid,
    OracleInternetDirectoryID : Guid,
    Name : string,
    Description : string,
},
…]

Response codes

200 – Request successful. Oracle Internet Directories in response body.

GET OracleInternetDirectories/{id}

Purpose

Returns an Oracle Internet Directory by ID.

Required permissions

Password Safe System Management (Read).

URL parameters

id: ID of the Oracle Internet Directory.

Request body

None.

Response body

Content-Type: application/json

{
    OrganizationID : Guid,
    OracleInternetDirectoryID : Guid,
    Name : string,
    Description : string,
}

Response codes

200 – Request successful. Oracle Internet Directory in response body.

GET Organizations/{id}/OracleInternetDirectories

Purpose

Returns a list of Oracle Internet Directories by organization ID.

Required permissions

Password Safe System Management (Read).

URL parameters

id: ID of the organization.

Request body

None.

Response body

Content-Type: application/json

[{
    OrganizationID : Guid,
    OracleInternetDirectoryID : Guid,
    Name : string,
    Description : string,
},
…]

Response codes

200 – Request successful. Oracle Internet Directories in response body.

POST OracleInternetDirectories/{id}/Services/Query

Purpose

Queries and returns DB Services for an Oracle Internet Directory by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

id: ID of the Oracle Internet Directory.

Request body

None.

Response body

Content-Type: application/json

{
    Success : bool,
    Message : string,
    Services : [{
    Name : string,
},
…]
}

Response codes

200 - Request successful. Oracle Internet Directory query result in response body.

POST OracleInternetDirectories/{id}/Test

Purpose

Tests the connection to an Oracle Internet Directory by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

id: ID of the Oracle Internet Directory.

Request body

None.

Response body

Content-Type: application/json

{
    Success : bool,
}

Response codes

200 – Request successful. Oracle Internet Directory test result in response body.

DSS key policies

ℹ️

Note

DSS Key Policies are formerly known as DSS Key Rules but the API remains DSSKeyRules to be compatible with earlier versions.

GET DSSKeyRules

Purpose

Returns a list of DSS Key Rules.

Required permissions

Password Safe System Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        DSSKeyRuleID: int, 
        Name: string, 
        Description: string, 
        KeyType: string, 
        KeySize: int, 
        EncryptionType: char,
        PasswordRuleID: int, // can be null
    },
    …
]

Response body details

• KeyType: (RSA, DSA) The type of key to generate.
• EncryptionType: The type of key encryption to use:
  • A: Auto-managed passphrase, generated using the associated password rule (see PasswordRuleID).
  • N: No encryption.
• PasswordRuleID: (given when EncryptionType is A) ID of the password rule used to auto-generate the passphrase for DSS key encryption.

Response codes

200 - Request successful. DSS Key Rules in the response body.

GET DSSKeyRules/{id}

Purpose

Returns a DSS Key Rule by ID.

Required permissions

Password Safe System Management (Read).

URL parameters

id: ID of the DSS Key Rule.

Request body

None.

Response body

Content-Type: application/json

{
    DSSKeyRuleID: int, 
    Name: string, 
    Description: string, 
    KeyType: string, 
    KeySize: int, 
    EncryptionType: char,
    PasswordRuleID: int, // can be null
}

Response body details

• KeyType: The type of key to generate (RSA, DSA).
• EncryptionType: The type of key encryption to use:
  • A: Auto-managed passphrase, generated using the associated password rule (see PasswordRuleID).
  • N: No encryption.
• PasswordRuleID: (given when EncryptionType is A) ID of the password rule used to auto-generate the passphrase for DSS key encryption.

Response codes

200 - Request successful. DSS Key Rule in the response body.

Entity types

Entity types define the types of entities within Password Safe (for example, asset, database, directory, and cloud).

GET EntityTypes

Purpose

Returns a list of entity types.

Required permissions

None.

Request body

None.

Response body

Content-Type: application/json

[
    {
        EntityTypeID: int,
        Name: string,
        Description: string,
    },
    …
]

Response codes

200 - Request successful. Entity types in the response body.

Functional accounts

GET FunctionalAccounts

Purpose

Returns a list of functional accounts.

Required permissions

Password Safe Account Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        FunctionalAccountID : int, 
        PlatformID : int, 
        DomainName : string, 
        AccountName : string, 
        DisplayName : string, 
        Description : string, 
        ElevationCommand : string, 
        SystemReferenceCount : int,
        TenantID : string,
        ObjectID : string,
        AzureInstance : string
    },
    …
]

Response body details

• PlatformID: ID of the platform to which the account belongs.
• DomainName: Domain name of the account.
• AccountName: Name of the account (does not include domain name).
• DisplayName: The display name or alias for the account.
• Description: Description of the account.
• ElevationCommand: Elevation command used for SSH connections (sudo, pbrun, pmrun).
• SystemReferenceCount: The count of managed systems that reference the functional account.
• TenantID: TenantID of the account (if applicable).
• ObjectID: ObjectID of the account (if applicable).
• AzureInstance: (optional)
  • For an AzureAD functional account, the AzureInstance property will return either AzurePublic or AzureUsGovernment
  • For a non-AzureAD functional account, the AzureInstance property will be an empty string ""

Response codes

200 - Request successful. Functional account in the response body.

GET FunctionalAccounts/{id}

Purpose

Returns a functional account by ID.

Required permissions

Password Safe Account Management (Read).

URL parameters

id: ID of the functional account.

Request body

None.

Response body

Content-Type: application/json

{
    FunctionalAccountID : int,
    PlatformID: int, DomainName : string, 
    AccountName : string, 
    DisplayName : string, 
    Description : string, 
    ElevationCommand : string, 
    SystemReferenceCount : int,
    TenantID : string,
    ObjectID : string,
    AzureInstance : string            
}

Response body details

• PlatformID: ID of the platform to which the account belongs.
• DomainName: Domain name of the account.
• AccountName: Name of the account (does not include domain name).
• DisplayName: The display name or alias for the account.
• Description: Description of the account.
• ElevationCommand: Elevation command used for SSH connections (sudo, pbrun, pmrun).
• SystemReferenceCount: The count of managed systems that reference the functional account.
• TenantID: TenantID of the account (if applicable).
• ObjectID: ObjectID of the account (if applicable).
• AzureInstance: (optional)
  • For an AzureAD functional account, the AzureInstance property will return either AzurePublic or AzureUsGovernment
  • For a non-AzureAD functional account, the AzureInstance property will be an empty string ""

Response codes

200 - Request successful. Functional Account in the response body.

POST FunctionalAccounts

Purpose

Creates a functional account.

Required permissions

Password Safe Account Management (Read/Write).

Request body

Content-Type: application/json

{
    PlatformID : int,
    DomainName : string,
    AccountName : string,
    DisplayName : string,
    Password : string,
    PrivateKey : string,
    Passphrase : string,
    Description : string,
    ElevationCommand : string,
    TenantID : string,
    ObjectID : string,
    Secret : string, 
    ServiceAccountEmail : string,
    AzureInstance : string
}

Request body details

• PlatformID: (required) ID of the platform to which the account belongs.
• DomainName: (optional) Domain name of the account. Can be set if Platform.DomainNameFlag is true. Max string length is 500.
• AccountName: (required) Name of the account (do not include domain name). Max string length is 245.
• DisplayName: (optional) The display name or alias for the account. If not given, uses the AccountName. Must be unique for the platform. Max string length is 100.
• Password: (required when Platform.RequiresSecret is false) The current account password.
• PrivateKey: (optional) DSS private key. Can be set if Platform.DSSFlag is true.
• Passphrase: (required when PrivateKey is an encrypted DSS key) DSS passphrase. Can be set if Platform.DSSFlag is true.
• Description: (optional) Description of the account. Max string length is 1000.
• ElevationCommand: (optional) Elevation command to use for SSH connections. Can be set if Platform.SupportsElevationFlag is true (sudo, pbrun, pmrun). Max string length is 80.
• TenantID: string (required when Platform.RequiresTenantID is true). Max string length is 36.
• ObjectID: string (required when Platform.RequiresObjectID is true). Max string length is 36.
• Secret: string (required when Platform.RequiresSecret is true). Max string length is 255.
• ServiceAccountEmail: string (required for Google functional accounts). Max string length is 255.
• AzureInstance: string (optional) Default value is AzurePublic when Platform = AzureAD (only supports values of AzurePublic and AzureUsGovernment if a value is provided - null or empty values default to AzurePublic).

Response body

Content-Type: application/json

{
    FunctionalAccountID : int,
    PlatformID : int,
    DomainName : string,
    AccountName : string,
    DisplayName : string,
    Description : string,
    ElevationCommand : string,
    SystemReferenceCount : int,
    TenantID : string,
    ObjectID : string,
    AzureInstance : string
}

Response body details

• PlatformID: ID of the platform to which the account belongs.
• DomainName: Domain name of the account.
• AccountName: Name of the account (does not include domain name).
• DisplayName: The display name or alias for the account.
• Description: Description of the account.
• ElevationCommand: Elevation command used for SSH connections (sudo, pbrun, pmrun).
• SystemReferenceCount: The count of managed systems that reference the functional account.
• TenantID: TenantID of the account (if applicable).
• ObjectID: ObjectID of the account (if applicable).
• AzureInstance: Default value is AzurePublic when Platform = AzureAD (supports values of AzurePublic and AzureUsGovernment only).

Response codes

201 - Request successful. Functional Account in the response body.

400 - Bad Request "Invalid Azure instance value"

DELETE FunctionalAccounts/{id}

Purpose

Deletes a functional account by ID.

Required permissions

Password Safe Account Management (Read/Write).

Other requirements

The functional account cannot be referenced by any managed systems.

URL parameters

id: ID of the functional account.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

ISA requests

The ISARequests endpoint is for Information Systems Administrator (ISA) role access.

POST ISARequests

Purpose

Creates a new Information Systems Administrator (ISA) release request and returns the requested credentials.

Similar to POST Requests (AccessType=View) and GET Credentials in a single call.

Required roles

ISA Role to managed account referenced by ID.

Query parameters

• type: (optional, default: password) Type of credentials to retrieve.
  • password: Returns the password in the response body.
  • dsskey: Returns the DSS private key in the response body.

ℹ️

Note

The key is returned in the state in which it was set. For example, an encrypted key is returned encrypted.

• passphrase: Returns the DSS key passphrase in the response body.

ℹ️

Note

passphrase supported only for encrypted DSS keys.

Request body

Content-Type: application/json

{
    SystemID: int,
    AccountID: int,
    DurationMinutes: int, // can be null
    Reason: string
}

Request body details

• SystemID: (required) ID of the managed system to request.
• AccountID: (required) ID of the managed account to request.
• DurationMinutes: (optional) The request duration (in minutes). If omitted, uses the value ManagedAccount.ISAReleaseDuration.
• Reason: (optional) The reason for the request.

Response body

{
    Credentials: string
}

Response codes

201 - Request successful. Credentials in the response body.

ISA sessions

The ISASessions endpoint is for Information Systems Administrator (ISA) role access.

POST ISASessions

Purpose

Creates a new Information Systems Administrator (ISA) release request and returns the requested session.

Similar to POST Requests and POST Sessions in a single call.

Required roles

• ISA role to managed account referenced by ID.

Request body

Content-Type: application/json

{
    SessionType : string,
    SystemID: int,
    AccountID: int,
    DurationMinutes : int, // can be null
    ApplicationID: int, // can be null
    Reason : string
}

Request body details

• SessionType: (required) The type of session to create.
• SystemID: (required) ID of the managed system to request.
• AccountID: (required) ID of the managed account to request.
• DurationMinutes: (optional) The request duration (in minutes). If omitted, uses the value ManagedAccount.ISAReleaseDuration.
• ApplicationID: (required when AccessType = App or AccessType = AppFile) ID of the application to request.
• Reason: (optional) The reason for the request.

Response body (SSH or sshticket)

Content-Type: application/json

{
    ID : string,
    Ticket : string,
    Host : string,
    Port : string,
    TicketAtHost : string,
    Link : string,
    Command : string
}

Response body (RDP or rdpticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string
}

Response body (rdpfile or appfile)

RDP file as an attachment.

Response codes

201- Request successful. Session details or RDP file in the response body.

Keystrokes

GET Sessions/{sessionId:int}/Keystrokes

Purpose

Returns a list of keystrokes by session ID.

Required roles

Password Safe Auditor role, ISA role, or a member of BeyondInsight Administrators group.

URL parameters

sessionId: ID of recorded RDP/SSH session.

Response body

Content-Type: application/json

[
    {
        KeystrokeID: long, 
        SessionID: int, 
        TimeMarker: long, 
        Type: byte,
        Data: string
    },
    …
]

Response codes

200 - Request successful. Keystrokes are in response body.

GET Keystrokes/{id:long}

Purpose

Returns a keystroke by ID.

Required roles

Password Safe Auditor role, ISA role, or a member of BeyondInsight Administrators group.

URL parameters

id: ID of a keystroke.

Response body

Content-Type: application/json

{
    KeystrokeID: long, 
    SessionID: int,
    TimeMarker: long, 
    Type: byte ,
    Data: string
}

Response codes

200 - Request successful. Keystroke in response body.

POST Keystrokes/Search

Purpose

Search for keystrokes.

Required roles

Password Safe Auditor role, ISA role, or a member of BeyondInsight Administrators group.

Request body

Content-Type: application/json

{
    Data: string,
    Type: byte
}

Request body details

• Data: (required) Keyword(s) for which to search.
• Type: (default: 0) Type of keystrokes:
  • 0: All
  • 1: StdIn
  • 2: StdOut
  • 4: Window Event
  • 5: User Event

Response body

Content-Type: application/json

[
    {
        KeystrokeID: long, 
        SessionID: int, 
        TimeMarker: long, 
        Type: byte,
        Data: string
    },
    …
]

Response codes

200 - Request successful. Keystrokes are in response body.

Linked accounts

Linked accounts are Directory managed accounts that are linked to asset-based managed systems.

ℹ️

Note

Directory accounts can be linked only to managed assets and managed databases.

GET ManagedSystems/{systemID}/LinkedAccounts

Purpose

Returns a list of linked directory managed accounts by managed system ID.

Required permissions

Password Safe System Management (Read).

URL parameters

systemID: ID of the managed system.

Request body

None.

Response body

Content-Type: application/json

[
    {
        ManagedAccountID : int,
        ManagedSystemID : int,
        DomainName : string,
        AccountName : string,
        DistinguishedName : string,
        PasswordFallbackFlag : bool,
        LoginAccountFlag : bool,
        Description : string,
        PasswordRuleID : int,
        ApiEnabled : bool,
        ReleaseNotificationEmail : string,
        ChangeServicesFlag : bool,
        RestartServicesFlag : bool,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        MaxConcurrentRequests : int,

        AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,

        ParentAccountID : int, // can be null
        IsSubscribedAccount : bool,
        LastChangeDate : datetime, // can be null
        NextChangeDate : datetime, // can be null
        IsChanging : bool,
        ChangeState : int,
        UseOwnCredentials : bool,
        ChangeIISAppPoolFlag : bool,
        RestartIISAppPoolFlag : bool,
        WorkgroupID : int, // can be null

        ChangeWindowsAutoLogonFlag : bool,
        ChangeComPlusFlag : bool,
        ChangeDComFlag : bool,
        ChangeSComFlag : bool,    
        },
    …
]

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (see ChangeServicesFlag), otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 means unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (see IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.

Response codes

200 - Request successful. Linked managed account in the response body.

POST ManagedSystems/{systemID}/LinkedAccounts/{accountID}

Purpose

Links a directory managed account to the managed system referenced by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

• systemID: ID of the managed system.
• accountID: ID of the directory managed account.

Request body

None.

Response body

Content-Type: application/json

{
    ManagedAccountID : int,
    ManagedSystemID : int,
    DomainName : string,
    AccountName : string,
    DistinguishedName : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,

    ParentAccountID : int, // can be null
    IsSubscribedAccount : bool,
    LastChangeDate : datetime, // can be null
    NextChangeDate : datetime, // can be null
    IsChanging: bool,
    ChangeState : int,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int, // can be null

    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,
}

Response body details

• AccountName: The name of the account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (see ChangeServicesFlag), otherwise false.
• ReleaseDuration:(minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 is unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.

Response codes

• 200 - Account was already linked. Directory Managed Account in the response body.
• 201 - Account was linked successfully. Directory Managed Account in the response body.

DELETE ManagedSystems/{systemID}/LinkedAccounts

Purpose

Unlinks all directory managed accounts from the managed system by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

systemID: ID of the managed system.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedSystems/{systemID}/LinkedAccounts/{accountID}

Purpose

Unlinks a directory managed account from the managed system by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

• systemID: ID of the managed system.
• accountID: ID of the directory managed account.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

Managed accounts

There are two different ways to interact with managed accounts:

1. Role-based:Requestor, Requestor/Approver, or ISA role assigned for requesting access to a specific managed account.
2. Permission-based: A user with appropriate Password Safe Account Management permission for provisioning accounts and viewing the definition of a managed account.

Role-based access

GET ManagedAccounts

ℹ️

Note

When specifying a directory managed account name in the GET ManagedAccounts API call, the account name must be in the UPN or Domain\AccountName format, even if the option type=domainlinked is specified.

For example:

GET managedaccounts?accountname=domain\directoryAccount&type=domainlinked

type=domainlinked is not necessary in the example above.

type=domainlinked can be used to limit the returned results to domain accounts when an account name is not included in the call. type=domainlinked can also be useful when you want to exclude local accounts when specifying the systemname.

If a managed account name is not specified, then type=domainlinked can be used to get all the domain linked accounts that the logged-in user has access to.

Purpose

Returns a list of managed accounts (or a single managed account depending on the query parameters provided) that can be requested by the current user.

Required roles

Requestor, Requestor/Approver, or ISA role.

Other requirements

Only managed accounts with the Enable for API Access setting enabled are returned.

Query parameters

• systemName: (optional) Name of the managed system.
• accountName: (optional) Name of the managed account.
• systemID: (optional) ID of the Managed System.
• workgroupName: (optional) Name of the Workgroup.
• applicationDisplayName: (optional, when given, type must be application) Display name of the application.
• ipAddress: (optional, when given type must be one of system, domainlinked, or database) IP Address of the managed asset.
• type: (optional/recommended) Type of the managed account to return.
  • system: Returns local accounts.
  • recent: Returns recently used accounts.
  • domainlinked: Returns domain accounts linked to systems.
  • database: Returns database accounts.
  • cloud: Returns cloud system accounts.
  • application: Returns application accounts
• limit: (optional) (default: 1000) Number of records to return
• offset: (optional) (default: 0) Number of records to skip before returning records

Request body

None

Response body (when both systemName or systemID, and accountName are given)

Content-Type: application/json

{
    PlatformID : int,
    SystemId : int,
    SystemName : string,
    DomainName : string,
    AccountId : int,
    AccountName : string,
    InstanceName : string,
    UserPrincipalName : string,
    ApplicationID : int,
    ApplicationDisplayName : string,
    DefaultReleaseDuration : int,
    MaximumReleaseDuration : int,
    LastChangeDate : datetime,
    NextChangeDate : datetime,
    IsChanging : bool,
    ChangeState : int,
    IsISAAccess : bool,
    PreferredNodeID : string
}

Response body (all other combinations of query parameters)

Content-Type: application/json

[
    {
    PlatformID : int,
    SystemId : int,
    SystemName : string,
    DomainName : string,
    AccountId : int,
    AccountName : string,
    InstanceName : string,
    UserPrincipalName : string,
    ApplicationID : int,
    ApplicationDisplayName : string,
    DefaultReleaseDuration : int,
    MaximumReleaseDuration : int,
    LastChangeDate : datetime,
    NextChangeDate : datetime,
    IsChanging : bool,
    ChangeState : int,
    IsISAAccess : bool,
    PreferredNodeID : string
    },
    …
]

Response body details

• PlatformID: ID of the managed system platform.
• SystemId: ID of the managed system.
• SystemName: Name of the managed system.
• DomainName: The domain name for a domain-type account.
• AccountId: ID of the managed account.
• AccountName: Name of the managed account.
• InstanceName: Database instance name of a database-type managed system, or empty for the default instance.
• UserPrincipalName: User Principal Name of the managed account.
• ApplicationID: ID of the application for application-based access.
• ApplicationDisplayName: Display name of the application for application-based access.
• DefaultReleaseDuration (minutes): Default release duration.
• MaximumReleaseDuration (minutes): Maximum release duration.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• IsISAAccess: True if the account is for Information Systems Administrator (ISA) access, otherwise false.

ℹ️

Note

If true, credential access is through POST ISARequests and session access is through POST ISASessions.

If false, credential access is through POST Requests and GET Credentials; session access is through POST Requests and POST Sessions.

• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.
• PreferredNodeID: ID of the node that is preferred for establishing sessions. If no node is preferred, returns the local node ID.

Response codes

200 - Request successful. Requestable Account(s) in the response body.

GET ManagedAccounts?systemName={systemName}&accountName={accountName}

ℹ️

Note

This API has had optional query parameters added to better isolate specific results as needed in specific applications while using GET ManagedAccounts.

Provisioning

GET ManagedAccounts/{id}

Purpose

Returns a managed account by ID.

Required permissions

Password Safe Account Management (Read).

URL parameters

id: ID of the managed account.

Request body

None.

Response body

Content-Type: application/json

{
    ManagedAccountID : int,
    ManagedSystemID : int,
    DomainName : string,
    AccountName : string,
    DistinguishedName : string,
    PasswordFallbackFlag : bool,
    UserPrincipalName : string,
    SAMAccountName : string,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,

    ParentAccountID : int, // can be null
    IsSubscribedAccount : bool,
    LastChangeDate: datetime, // can be null
    NextChangeDate: datetime, // can be null
    IsChanging: bool
    ChangeState : int,
    UseOwnCredentials: bool,
    WorkgroupID : int // can be null
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    ObjectID : string
}

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• UserPrincipalName: (Active Directory managed systems only) The account user principal name of an Active Directory account.
• SAMAccountName: (Active Directory managed systems only) The account SAM account name of an Active Directory account.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, default: 1) Maximum number of concurrent password requests for this account. A value of zero denotes unlimited requests.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / No change taking place or scheduled within 5 minutes.
  • 1: Changing / Managed Account Credential currently changing.
  • 2: Queued / Managed Account Credential is queued to change or scheduled to change within 5 minutes.
• UseOwnCredentials: True if the current account credentials should be used during change operations, otherwise false.
• WorkgroupID: ID of the assigned Workgroup.
• ObjectID: (required when Platform.RequiresObjectID is true). ObjectID of the account (if applicable).

Response code

200 - Request successful. Managed Account in the response body.

GET ManagedSystems/{systemID}/ManagedAccounts

Purpose

Returns a list of managed accounts by managed system ID.

Required permissions

Password Safe Account Management (Read).

URL parameters

systemID: ID of the managed system.

Request body

None.

Response body

Content-Type: application/json

[
{
    ManagedAccountID : int,
    ManagedSystemID : int,
    DomainName : string,
    AccountName : string,
    DistinguishedName : string,
    PasswordFallbackFlag : bool,
    UserPrincipalName : string,
    SAMAccountName : string,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,

    ParentAccountID : int, // can be null
    IsSubscribedAccount : bool,
    LastChangeDate : datetime, // can be null
    NextChangeDate : datetime, // can be null
    IsChanging : bool,
    ChangeState : int,
    UseOwnCredentials : bool,
    WorkgroupID : int // can be null
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int, // can be null
    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,

    },
    …
]

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• UserPrincipalName: (Active Directory managed systems only) The account user principal name of an Active Directory account.
• SAMAccountName: (Active Directory managed systems only) The account SAM account name of an Active Directory account.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, default: 1) Maximum number of concurrent password requests for this account. A value of zero denotes unlimited requests.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.
• WorkgroupID: ID of the assigned Workgroup.

Response codes

200 - Request successful. Managed Account in the response body.

GET ManagedSystems/{systemID}/ManagedAccounts?name={name}

Purpose

Returns a managed account by managed system ID and managed account name.

Required permissions

Password Safe Account Management (Read).

URL parameters

systemID: ID of the managed system.

Query parameters

name: Name of the managed account.

Request body

None.

Response body

Content-Type: application/json

{
    ManagedAccountID : int,
    ManagedSystemID : int,
    DomainName : string,
    AccountName : string,
    DistinguishedName : string,
    PasswordFallbackFlag : bool,
    UserPrincipalName : string,
    SAMAccountName : string,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,

    ParentAccountID : int, // can be null
    IsSubscribedAccount : bool,
    LastChangeDate: datetime, // can be null
    NextChangeDate: datetime, // can be null
    IsChanging: bool
    ChangeState : int,
    UseOwnCredentials: bool,
    WorkgroupID : int // can be null
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
}

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• UserPrincipalName: (Active Directory managed systems only) The account user principal name of an Active Directory account.
• SAMAccountName: (Active Directory managed systems only) The account SAM account name of an Active Directory account.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, default: 1) Maximum number of concurrent password requests for this account. A value of zero denotes unlimited requests.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / No change taking place or scheduled within 5 minutes.
  • 1: Changing / Managed Account Credential currently changing.
  • 2: Queued / Managed Account Credential is queued to change or scheduled to change within 5 minutes.
• UseOwnCredentials: True if the current account credentials should be used during change operations, otherwise false.
• WorkgroupID: ID of the assigned Workgroup.

Response codes

200 - Request successful. Managed Account in the response body.

PUT ManagedAccounts/{id}

Purpose

Updates an existing managed account by ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• id: ID of the managed account.
• version: (optional, default: 3.0) Request body model version (3.0, 3.1, 3.2, 3.3, 3.4, 3.5).

Request body (version 3.0)

Content-Type: application/json

{
    AccountName : string,
    ManagedSystemID: int,
    Password : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string
}

Request body (version 3.1)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool
}

Request body (version 3.2)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool
}

Request body (version 3.3)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int // can be null
}

Request body (version 3.4)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int // can be null,
    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,

}

Request body (version 3.5)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        NextChangeDate : date-formatted string,
    
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int // can be null,
    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,
            
    ObjectID : string
}

Request body details

• AccountName: (required) The name of the account. Must be unique on the system. Max string length is 245.
• ManagedSystemID: (required) ID of the managed system.
• Password: (required if AutoManagementFlag is false) The account password.
• DomainName: (optional) This can be given but it must be exactly the same as the directory. If empty or null, it is automatically populated from the parent managed system/directory. Max string length is 50.
• UserPrincipalName: (required for Active Directory managed systems only) The Active Directory user principal name. Max string length is 500.
• SAMAccountName: (required for Active Directory managed systems only) The Active Directory SAM account name (maximum 20 characters). Max string length is 20.
• DistinguishedName: (required for LDAP Directory managed systems only) The LDAP distinguished name. Max string length is 1000.
• PrivateKey: DSS private key. Can be set if Platform.DSSFlag is true.
• Passphrase: (required when PrivateKey is an encrypted DSS key) DSS passphrase. Can be set if Platform.DSSFlag is true.
• PasswordFallbackFlag: (default: false) True if failed DSS authentication can fall back to password authentication, otherwise false. Can be set if Platform.DSSFlag is true.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false. Can be set when the ManagedSystem.LoginAccountID is set.
• Description: A description of the account. Max string length is 1024.
• PasswordRuleID: (default: 0) ID of the password rule assigned to this managed account.
• ApiEnabled: (default: false) True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account. Max string length is 255.
• ChangeServicesFlag: (default: false) True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: (default: false) True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: (default: false) True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 is unlimited, default: 1) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: (default: false) True if DSS key auto-management is enabled, otherwise false. If set to true, and no PrivateKey is provided, immediately attempts to generate and set a new public key on the server. Can be set if Platform.DSSAutoManagementFlag is true.
  • CheckPasswordFlag: (default: false) True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: (default: false) True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: (default: false) True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: (default: first) The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59, default: 23:30) UTC time of day scheduled password changes take place.
  • NextChangeDate: (date format: YYYY-MM-DD) UTC date when next scheduled password change occurs. If the NextChangeDate + ChangeTime is in the past, password change occurs at the nearest future ChangeTime.
• UseOwnCredentials: (version 3.1+) True if the current account credentials should be used during change operations, otherwise false.
• ChangeIISAppPoolFlag: (version 3.2 only) True if IIS Application Pools run, as this user should be updated with the new password after a password change, otherwise false.
• RestartIISAppPoolFlag: (version 3.2 only) True if IIS Application Pools should be restarted after the run as password is changed (ChangeIISAppPoolFlag), otherwise false.
• WorkgroupID: ID of the assigned Workgroup.
• ChangeWindowsAutoLogonFlag: (default: false) True if Windows Auto Logon should be updated with the new password after a password change, otherwise false.
• ChangeComPlusFlag: (default: false) True if COM+ Apps should be updated with the new password after a password change, otherwise false.
• ChangeDComFlag: (default: false) True if DCOM Apps should be updated with the new password after a password change, otherwise false.
• ChangeSComFlag: (default: false) True if SCOM Identities should be updated with the new password after a password change, otherwise false.
• ObjectID: (required when Platform.RequiresObjectID is true). ObjectID of the account (if applicable). Max string length is 36.

Response body

Content-Type: application/json

{
    ManagedAccountID : int,
    ManagedSystemID : int,
    DomainName : string,
    AccountName : string,
    DistinguishedName : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,

    ParentAccountID : int, // can be null
    IsSubscribedAccount : bool,
    LastChangeDate: datetime, // can be null
    NextChangeDate: datetime, // can be null
    IsChanging: bool,
    ChangeState : int,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int, // can be null
    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,
    ObjectID : string
}

Response codes

200 - Request successful. Managed Account in the response body.

POST ManagedSystems/{systemID}/ManagedAccounts

Purpose

Creates a new managed account in the managed system referenced by ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

systemID: ID of the managed system.

Query parameters

version: (optional, default: 3.0) Request body model version (3.0, 3.1, 3.2, 3.3, 3.4, 3.5).

Request body (version 3.0)

Content-Type: application/json

{
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string
}

Request body (version 3.1)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool
}

Request body (version 3.2)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool
}

Request body (version 3.3)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int // can be null
}

Request body (version 3.4)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    NextChangeDate : date-formatted string,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int // can be null,
    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,

}

Request body (version 3.5)

Content-Type: application/json

{ 
    AccountName : string,
    Password : string,
    DomainName : string,
    UserPrincipalName : string,
    SAMAccountName : string,
    DistinguishedName : string,
    
    PrivateKey : string,
    Passphrase : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        NextChangeDate : date-formatted string,
        
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int // can be null,
    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,

    ObjectID : string
}

Request body details

• AccountName: (required) The name of the account. Must be unique on the system. Max string length is 245.
• Password: (required if AutoManagementFlag is false) The account password.
• DomainName: (optional) This can be given but it must be exactly the same as the directory. If empty or null, it is automatically populated from the parent managed system/directory. Max string length is 50.
• UserPrincipalName: (required for Active Directory and Entra ID managed systems only) The Active Directory user principal name. Max string length is 500.
• SAMAccountName: (required for Active Directory managed systems, optional for Entra ID managed systems) The Active Directory SAM account name (Maximum 20 characters). Max string length is 20.
• DistinguishedName: (required for LDAP Directory managed systems only) The LDAP distinguished name. Max string length is 1000.
• PrivateKey: DSS private key. Can be set if Platform.DSSFlag is true.
• Passphrase: (required when PrivateKey is an encrypted DSS key) DSS passphrase. Can be set if Platform.DSSFlag is true.
• PasswordFallbackFlag: (default: false) True if failed DSS authentication can fall back to password authentication, otherwise false. Can be set if Platform.DSSFlag is true.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false. Can be set when the ManagedSystem.LoginAccountID is set.
• Description: A description of the account. Max string length is 1024.
• PasswordRuleID: (default: 0) ID of the password rule assigned to this managed account.
• ApiEnabled: (default: false) True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account. Max string length is 255.
• ChangeServicesFlag: (default: false) True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: (default: false) True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: (default: false) True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 is unlimited, default: 1) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: (default: false) True if DSS key auto-management is enabled, otherwise false. If set to true, and no PrivateKey is provided, immediately attempts to generate and set a new public key on the server. Can be set if Platform.DSSAutoManagementFlag is true.
  • CheckPasswordFlag: (default: false) True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: (default: false) True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: (default: false) True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: (default: first) The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59, default: 23:30) UTC time of day scheduled password changes take place.
  • NextChangeDate: (date format: YYYY-MM-DD) UTC date when next scheduled password change occurs. If the NextChangeDate + ChangeTime is in the past, password change occurs at the nearest future ChangeTime.
• UseOwnCredentials: (version 3.1+) True if the current account credentials should be used during change operations, otherwise false.
• ChangeIISAppPoolFlag: (version 3.2 only) True if IIS application pools run as this user should be updated with the new password after a password change, otherwise false.
• RestartIISAppPoolFlag: (version 3.2 only) True if IIS application pools should be restarted after the run as password is changed (ChangeIISAppPoolFlag), otherwise false.
• WorkgroupID: ID of the assigned Workgroup.
• ChangeWindowsAutoLogonFlag: (default: false) True if Windows Auto Logon should be updated with the new password after a password change, otherwise false.
• ChangeComPlusFlag: (default: false) True if COM+ Apps should be updated with the new password after a password change, otherwise false.
• ChangeDComFlag: (default: false) True if DCOM Apps should be updated with the new password after a password change, otherwise false.
• ChangeSComFlag: (default: false) True if SCOM Identities should be updated with the new password after a password change, otherwise false.
• ObjectID: (required when Platform.RequiresObjectID is true). ObjectID of the account (if applicable). Max string length is 36.

Response body

Content-Type: application/json

{
    ManagedAccountID : int,
    ManagedSystemID : int,
    DomainName : string,
    AccountName : string,
    DistinguishedName : string,
    PasswordFallbackFlag : bool,
    UserPrincipalName : string,
    SAMAccountName : string,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ChangeTasksFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,

    ParentAccountID : int, // can be null
    IsSubscribedAccount : bool,
    LastChangeDate : datetime, // can be null
    NextChangeDate : datetime, // can be null
    IsChanging : bool,  
    ChangeState : int,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int, // can be null
    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,
    ObjectID : string
}

Response body details

• AccountName: The name of the account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• UserPrincipalName: (Active Directory and Entra ID managed systems only) The account user principal name of an Active Directory account.
• SAMAccountName: (Active Directory managed systems, optional for Entra ID managed systems) The account SAM account name of an Active Directory account.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 means unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account, this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.
• UseOwnCredentials: True if the current account credentials should be used during change operations, otherwise false.
• ChangeIISAppPoolFlag: True if IIS application pools run as this user should be updated with the new password after a password change, otherwise false.
• RestartIISAppPoolFlag: True if IIS application pools should be restarted after the run as password is changed, otherwise false.
• WorkgroupID: ID of the assigned Workgroup.
• ChangeWindowsAutoLogonFlag: True if Windows auto logon should be updated with the new password after a password change, otherwise false.
• ChangeComPlusFlag: True if COM+ apps should be updated with the new password after a password change, otherwise false.
• ChangeDComFlag: True if DCOM apps should be updated with the new password after a password change, otherwise false.
• ChangeSComFlag: True if SCOM identities should be updated with the new password after a password change, otherwise false.
• ObjectID: ObjectID of the account (if applicable).

Response codes

201 - Request successful. Managed Account in the response body.

DELETE ManagedAccounts/{id}

Purpose

Deletes a managed account by ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

id: ID of the managed account.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedSystems/{systemID}/ManagedAccounts/{accountName}

Purpose

Deletes a managed account by managed system ID and managed account name.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• systemID: ID of the managed system.
• accountName: Name of the managed account.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedSystems/{id}/ManagedAccounts

Purpose

Deletes all managed accounts on the managed system by ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• id: ID of the managed system.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

PUT ManagedAccounts/{managedAccountID}/Credentials

Purpose

Updates the credentials for a managed account, optionally applying the change to the managed system.

Required permissions

Requires one of the following:

• Password Safe Account Management (Read/Write).
• ISA Role or Credentials Manager Role on a Smart Rule referencing the account.

URL parameters

managedAccountID: ID of the managed account for which to set the credentials.

Request body

Content-Type: application/json

{
    Password: string, 
    PublicKey: string, 
    PrivateKey: string, 
    Passphrase: string, 
    UpdateSystem: bool
}

Request body details

• Password: (optional) The new password to set. If not given, generates a new random password.
• PublicKey: (required if PrivateKey is given and updateSystem = true) The new public key to set on the host.
• PrivateKey: The private key to set (provide passphrase if encrypted).
• Passphrase: (optional) The passphrase to use for an encrypted private key.
• UpdateSystem: (default: true) Whether to update the credentials on the referenced system.

Response body

None.

Response codes

204 - Request successful. No content in body.

PUT Credentials?workgroupName={workgroupName}&assetName={assetName}&accountName={accountName}

Purpose

Updates the credentials for a managed account by Workgroup name, asset name, and managed account name, optionally applying the change to the managed system.

Required permissions

Requires one of the following:

• Password Safe Account Management (Read/Write).
• ISA Role or Credentials Manager Role on a Smart Rule referencing the account.

Query parameters

• workgroupName: Name of the Workgroup.
• assetName: Name of the asset.
• accountName: Name of the managed account for which to set the credentials.

Request body

Content-Type: application/json

{
    Password: string,
    PublicKey: string,
    PrivateKey: string,
    Passphrase: string,
    UpdateSystem: bool
}

Request body details

• Password: (optional) The new password to set. If not given, generates a new random password.
• PublicKey: (required if PrivateKey is given and updateSystem = true) The new public key to set on the host.
• PrivateKey: The private key to set (provide passphrase if encrypted).
• Passphrase: (optional) The passphrase to use for an encrypted private key.
• UpdateSystem: (default: true) Whether to update the credentials on the referenced system.

Response body

None.

Response codes

204 - Request Successful. No Response Body.

POST ManagedAccounts/{managedAccountID}/Credentials/Test

Purpose

Tests the current credentials of a managed account.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

managedAccountID: ID of the managed account.

Request body

None.

Response body

Content-Type: application/json

{
    Success : bool
}

Response body details

Success: True if the credential test succeeded, otherwise false.

Response codes

200 - Request Successful.

POST ManagedAccounts/{managedAccountID}/Credentials/Change

Purpose

Changes the current credentials of a managed account.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

managedAccountID: ID of the managed account.

Request body (optional)

Content-Type: application/json

{
    Queue : bool
}

Request body details

Queue: (default: false) True to queue the change for background processing, otherwise false. When Queue is false the credentials change is immediate.

Response body

None.

Response codes

204 - Request successful. No content in body.

POST ManagedSystems/{systemId}/ManagedAccounts/Credentials/Change

Purpose

Queues credentials' changes for all active managed accounts for a managed system.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

systemId: ID of the managed system.

Request body

None.

Response body

None.

Response codes

204 - Request successful. No content in body.

Quick rule managed accounts

GET QuickRules/{quickRuleID}/ManagedAccounts

Purpose

Returns a list of managed accounts by Quick Rule ID.

Required permissions

Read access to the Quick Rule.

URL parameters

quickRuleID: ID of the Quick Rule.

Request body

None.

Response body

Content-Type: application/json

[
    {
        ManagedAccountID : int,
        ManagedSystemID : int,
        DomainName : string,
        AccountName : string,
        DistinguishedName : string,
        PasswordFallbackFlag : bool,
        LoginAccountFlag : bool,
        Description : string,
        PasswordRuleID : int,
        ApiEnabled : bool,
        ReleaseNotificationEmail : string,
        ChangeServicesFlag : bool,
        RestartServicesFlag : bool,
        ChangeTasksFlag : bool,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        MaxConcurrentRequests : int,

        AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,

        ParentAccountID : int, // can be null
        IsSubscribedAccount : bool,
        LastChangeDate : datetime, // can be null
        NextChangeDate : datetime, // can be null
        IsChanging : bool,
        ChangeState : int,
        UseOwnCredentials : bool,
        ChangeIISAppPoolFlag : bool,
        RestartIISAppPoolFlag : bool,
        WorkgroupID : int // can be null
        ChangeWindowsAutoLogonFlag : bool,
        ChangeComPlusFlag : bool,
        ChangeDComFlag : bool,
        ChangeSComFlag : bool,            
    },
    …
]

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 is unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.
• UseOwnCredentials: True if the current account credentials should be used during change operations, otherwise false.
• ChangeIISAppPoolFlag: True if IIS application pools run as this user should be updated with the new password after a password change, otherwise false.
• RestartIISAppPoolFlag: True if IIS application pools should be restarted after the run as password is changed, otherwise false.
• WorkgroupID: ID of the assigned Workgroup.

Response codes

200 – Request successful. Managed Accounts in the response body.

PUT QuickRules/{quickRuleID}/ManagedAccounts

Purpose

Updates the entire list of managed accounts in a Quick Rule by removing all Managed Account Fields - Quick Group ID filters and adding a new one with the managed accounts referenced by ID.

Required permissions

• Password Safe Account Management (Read).
• Read/Write access to the Quick Rule.

URL parameters

quickRuleID: ID of the Quick Rule.

Request body

Content-Type: application/json

{
    AccountIDs: [ int, …]
}

Response body

Content-Type: application/json

[
    {
        ManagedAccountID : int,
        ManagedSystemID : int,
        DomainName : string,
        AccountName : string,
        DistinguishedName : string,
        PasswordFallbackFlag : bool,
        LoginAccountFlag : bool,
        Description : string,
        PasswordRuleID : int,
        ApiEnabled : bool,
        ReleaseNotificationEmail : string,
        ChangeServicesFlag : bool,
        RestartServicesFlag : bool,
        ChangeTasksFlag : bool,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        MaxConcurrentRequests : int,

        AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        ParentAccountID : int, // can be null

        IsSubscribedAccount : bool,
        LastChangeDate: datetime, // can be null
        NextChangeDate: datetime, // can be null
        IsChanging: bool,
        ChangeState : int,
        UseOwnCredentials : bool,
        ChangeIISAppPoolFlag : bool,
        RestartIISAppPoolFlag : bool,
        WorkgroupID : int // can be null
        ChangeWindowsAutoLogonFlag : bool,
        ChangeComPlusFlag : bool,
        ChangeDComFlag : bool,
        ChangeSComFlag : bool,    
    },
    …
]

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 is unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.
• UseOwnCredentials: True if the current account credentials should be used during change operations, otherwise false.
• ChangeIISAppPoolFlag: True if IIS application pools run as this user should be updated with the new password after a password change, otherwise false.
• RestartIISAppPoolFlag: True if IIS application pools should be restarted after the run as password is changed, otherwise false.
• WorkgroupID: ID of the assigned Workgroup.

Response codes

200 – Request successful. Managed Accounts in the response body.

POST QuickRules/{quickRuleID}/ManagedAccounts/{accountID}

Purpose

Adds the managed account referenced by ID to the Quick Rule by adding it to the first Managed Account Fields - Quick Group ID filter found.

Required permissions

• Password Safe Account Management (Read).
• Read/Write access to the Quick Rule.

URL parameters

• quickRuleID: ID of the Quick Rule.
• accountID: ID of the managed account.

Request body

None.

Response body

Content-Type: application/json

[
    {
        ManagedAccountID : int,
        ManagedSystemID : int,
        DomainName : string,
        AccountName : string,
        DistinguishedName : string,
        PasswordFallbackFlag : bool,
        LoginAccountFlag : bool,
        Description : string,
        PasswordRuleID : int,
        ApiEnabled : bool,
        ReleaseNotificationEmail : string,
        ChangeServicesFlag : bool,
        RestartServicesFlag : bool,
        ChangeTasksFlag : bool,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        MaxConcurrentRequests : int,

        AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,

        ParentAccountID : int, // can be null
        IsSubscribedAccount : bool,
        LastChangeDate : datetime, // can be null
        NextChangeDate : datetime, // can be null
        IsChanging : bool,
        ChangeState : int,
        UseOwnCredentials : bool,
        ChangeIISAppPoolFlag : bool,
        RestartIISAppPoolFlag : bool,
        WorkgroupID : int, // can be null
        ChangeWindowsAutoLogonFlag : bool,
        ChangeComPlusFlag : bool,
        ChangeDComFlag : bool,
        ChangeSComFlag : bool,        
    },
    …
]

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 means unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.

Response codes

200 – Request successful. Managed Accounts in the response body.

DELETE QuickRules/{quickRuleID}/ManagedAccounts/{accountID}

Purpose

Removes the managed account referenced by ID from the Quick Rule by removing it from all Managed Account Fields - Quick Group ID filters found.

⚠️

Important

A rule cannot be left in an invalid state. If removing the account would result in an empty filter, the filter itself will be removed. If there are no filters left in the rule, a "400 Bad Request" is returned.

• If you intend to replace all accounts in the rule, see PUT QuickRules/{quickRuleID}/ManagedAccounts.
• If you intend to delete the rule, see DELETE QuickRules/{id}.

Required permissions

• Read/Write access to the Quick Rule.

URL parameters

• quickRuleID: ID of the Quick Rule.
• accountID: ID of the managed account.

Request body

None.

Response codes

200 – Request successful.

Smart Rule managed accounts

GET SmartRules/{smartRuleID}/ManagedAccounts

Purpose

Returns a list of managed accounts by Smart Rule ID.

Required permissions

Read access to the Smart Rule.

URL parameters

smartRuleID: ID of the Smart Rule.

Request body

None.

Response body

Content-Type: application/json

[
    {
        ManagedAccountID : int,
        ManagedSystemID : int,
        DomainName : string,
        AccountName : string,
        DistinguishedName : string,
        PasswordFallbackFlag : bool,
        LoginAccountFlag : bool,
        Description : string,
        PasswordRuleID : int,
        ApiEnabled : bool,
        ReleaseNotificationEmail : string,
        ChangeServicesFlag : bool,
        RestartServicesFlag : bool,
        ChangeTasksFlag : bool,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        MaxConcurrentRequests : int,

        AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,

        ParentAccountID : int, // can be null
        IsSubscribedAccount : bool,
        LastChangeDat e: datetime, // can be null
        NextChangeDate : datetime, // can be null
        IsChanging : bool,
        ChangeState : int,
        UseOwnCredentials : bool,
        ChangeIISAppPoolFlag : bool,
        RestartIISAppPoolFlag : bool,
        WorkgroupID : int // can be null

    },
    …
]

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ChangeTasksFlag: True if scheduled tasks run as this user should be updated with the new password after a password change, otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 means unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / No change taking place or scheduled within 5 minutes.
  • 1: Changing / Managed Account Credential currently changing.
  • 2: Queued / Managed Account Credential is queued to change or scheduled to change within 5 minutes.
• WorkgroupID: ID of the assigned Workgroup.

Response codes

200 - Request successful. Managed Accounts in the response body.

Managed account applications

GET ManagedAccounts/{accountID}/Applications

Purpose

Returns a list of applications assigned to a managed account.

Required permissions

Password Safe Account Management (Read).

URL parameters

accountID: ID of the managed account.

Request body

None.

Response body

Content-Type: application/json

[
    {
        ApplicationID : int,
        Name : string,
        DisplayName : string,
        Version : string,
        Command : string,
        Parameters : string,
        Publisher : string,
        ApplicationType : string,
        FunctionalAccountID : int, // can be null
        ManagedSystemID : int, // can be null
        IsActive : bool,
     SmartRuleID : int // can be null
    }
    …
]

Response codes

200 - Request successful. Applications in response body.

POST ManagedAccounts/{accountID}/Applications/{applicationID}

Purpose

Assigns an application to a managed account.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• accountID: ID of the managed account.
• applicationID: ID of the application.

Request body

None.

Response body

Content-Type: application/json

{
    ApplicationID : int,
    Name : string,
    DisplayName : string,
    Version : string,
    Command : string,
    Parameters : string,
    Publisher : string,
    ApplicationType : string,
    FunctionalAccountID : int, // can be null
    ManagedSystemID : int, // can be null
    IsActive : bool,
    SmartRuleID : int // can be null    
}

Response codes

201 - Request successful. Application in response body.

DELETE ManagedAccounts/{accountID}/Applications/{applicationID}

Purpose

Unassigns an application from a managed account by managed account ID and application ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• accountID: ID of the managed account.
• applicationID: ID of the application.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedAccounts/{accountID}/Applications

Purpose

Unassigns all managed account applications by managed account ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• accountID: ID of the managed account.
• applicationID: ID of the application.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

Managed systems

GET ManagedSystems

Purpose

Returns a list of managed systems.

Required permissions

Password Safe System Management (Read).

Query parameters (optional)

• type: The entity type of the managed system.
• name: The name of the managed system.
• limit: (default: 100000) Number of records to return.
• offset: (default: 0) Number of records to skip before returning records (can only be used in conjunction with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[
    {
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body (when limit is given)

Content-Type: application/json

[
    {
        TotalCount : int,
        Data : [{
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
        },
    …]
}

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed system in response body.

GET ManagedSystems/{id}

Purpose

Returns a managed system by ID.

Required permissions

Password Safe System Management (Read).

URL parameters

id: ID of the managed system.

Request body

None.

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed System in response body.

GET Assets/{assetId}/ManagedSystems

Purpose

Returns a managed system for the asset referenced by ID.

Required permissions

Password Safe System Management (Read).

URL parameters

assetId: ID of the asset.

Request body

None.

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed System in response body.

GET Databases/{databaseID}/ManagedSystems

Purpose

Returns a managed system for the database referenced by ID.

Required permissions

Password Safe System Management (Read).

URL parameters

databaseID: ID of the database.

Request body

None.

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        AccessURL : string
    },
    …
]

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed System in response body.

GET FunctionalAccounts/{id}/ManagedSystems

Purpose

Returns a list of managed systems auto-managed by the functional account referenced by ID.

Required permissions

Password Safe System Management (Read).

Password Safe Account Management (Read).

URL parameters

id: ID of the functional account.

Query parameters (optional)

• type: The entity type of the managed system.
• name: The name of the managed system.
• limit: (default: 100000) Number of records to return.
• offset: (default: 0) Number of records to skip before returning records (can only be used in conjunction with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[
    {
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body (when limit is given)

Content-Type: application/json

[
    {
        TotalCount : int,
        Data : [{
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed System in response body.

GET Workgroups/{id}/ManagedSystems

Purpose

Returns a list of managed systems by Workgroup ID.

Required permissions

Password Safe System Management (Read).

URL parameters

id: ID of the Workgroup.

Query parameters (optional)

• limit: (default: 100000) Number of records to return.
• offset: (default: 0) Number of records to skip before returning records (can be used only in conjunction with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[
    {
        WorkgroupID : int,
        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null

        HostName : string,
        IPAddress : string,
        DnsName : string,
        InstanceName : string,
        IsDefaultInstance : bool, // can be null
        Template : string,
        ForestName : string,
        UseSSL : bool, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,

        SystemName : string,
        PlatformID : int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool
        AccessURL : string
    },
…]

Response body (when limit is given)

Content-Type: application/json

{ 
    TotalCount : int,
    Data :
    [{ 
        WorkgroupID : int,
        ManagedSystemID : int,
        EntityTypeID: int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null

        HostName : string,
        IPAddress : string,
        DnsName : string,
        InstanceName : string,
        IsDefaultInstance : bool, // can be null
        Template : string,
        ForestName : string,
        UseSSL : bool, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,

        SystemName : string,
        PlatformID : int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …]
}

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed System in response body.

PUT ManagedSystems/{id}

Purpose

Updates an existing managed system by ID.

ℹ️

Note

PUT ManagedSystems/{id} supports all managed system types: dynamic asset, static asset, dynamic database, static database, directory, and cloud.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

id: ID of the managed system.

Query parameters

Version: (optional, default: 3.0) Request body model version (3.0, 3.1, 3.2, 3.3)

Request body (version 3.0)

Content-Type: application/json

{
    WorkgroupID : int,

    HostName : string,

    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null

    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    AccessURL : string
}

Request body (version 3.1)

Content-Type: application/json

{
    WorkgroupID : int,

    HostName : string,

    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null

    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string,
    AccessURL : string
}

Request body (version 3.2)

Content-Type: application/json

{
    WorkgroupID : int,
    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null
    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string,
    ApplicationHostID : int, // can be null
    IsApplicationHost : bool,
    AccessURL : string
}

Request body (version 3.3)

Content-Type: application/json

{
    WorkgroupID : int,
    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null
    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string,
    ApplicationHostID : int, // can be null
    IsApplicationHost : bool,
    AccessURL : string
}

Request body details

• WorkgroupID: ID of the Workgroup.
• HostName: (required) Name of the host (applies to Static Asset, Static Database, Directory, Cloud). Max string length is 128 characters.
  • Static Asset: Asset Name.
  • Static Database: Database Host Name.
  • Directory: Directory/Domain Name.
  • Cloud: Cloud System Name.
• IPAddress: IPv4 address of the host (applies to Static Asset, Static Database).
• DnsName: DNS name of the host (applies to Static Asset, Static Database).
• InstanceName: Name of the database instance. Required when IsDefaultInstance is false (applies to Static Database only).
• IsDefaultInstance: True if the database instance is the default instance, otherwise false. Only Platforms MS SQL Server and MySQL support setting this value to true (applies to Static Database only).
• Template: The database connection template (applies to Static Database only).
• ForestName: Name of the Directory Forest (applies to Directory only).
• UseSSL (default: false) True to use an SSL connection, otherwise false (applies to Directory only).
• PlatformID: (required) ID of the Managed System Platform.
• NetBiosName: The NetBIOS name of the host. Can be set if Platform.NetBiosNameFlag is true.
• Port: (optional) The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds, default: 30) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: (default: 0/None) Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto - Auto Accept Initial Key.
  • 2: Strict - Manually Accept Keys.
• PasswordRuleID: (default: 0) ID of the default Password Rule assigned to Managed Accounts created under this Managed System.
• DSSKeyRuleID: (default: 0) ID of the default DSS Key Rule assigned to Managed Accounts created under this Managed System. Can be set when Platform.DSSFlag is true.
• LoginAccountID: (optional) ID of the Functional Account used for SSH Session logins. Can be set if the Platform.LoginAccountFlag is true.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false. Can be set if Platform.AutoManagementFlag is true.
  • FunctionalAccountID: (required if AutoManagementFlag is true) ID of the Functional Account used for local Managed Account password changes. FunctionalAccount.PlatformID must either match the ManagedSystem.PlatformID or be a Directory Platform (AD, LDAP).
  • ElevationCommand: (optional) Elevation Command to use. Can be set if Platform.SupportsElevationFlag is true.
    • sudo
      • pbrun
      • pmrun
• CheckPasswordFlag: True to enable password testing, otherwise false.
• ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
• ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
• RemoteClientType: (default: none) The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: (default: null, required when Platform.RequiresApplicationHost = true) Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: (default: false) True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: (default: Default URL for the selected platform) The URL used for cloud access (applies to cloud systems only). Max string length is 2048.

Response body

Content-Type: application/json

{
    WorkgroupID : int,
    ManagedSystemID : int,
    EntityTypeID: int,
    AssetID : int, // can be null
    DatabaseID : int, // can be null
    DirectoryID : int, // can be null
    CloudID : int, // can be null

    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null

    SystemName : string,
    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    AccountNameFormat : int,
    OracleInternetDirectoryID : guid, // can be null
    OracleInternetDirectoryServiceName : string,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string,
    ApplicationHostID : int, // can be null
    IsApplicationHost : bool,
    AccessURL : string
}

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed System in response body.

POST Assets/{assetId}/ManagedSystems

Purpose

Creates a managed system for the asset referenced by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

assetId: ID of the asset.

Query parameters

Version: (optional, default: 3.0) Request body model version (3.0, 3.1, 3.2)

Request body (version 3.0)

Content-Type: application/json

{
    PlatformID : int,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,

    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
}

Request body (version 3.1)

Content-Type: application/json

{
    PlatformID : int,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,

    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string
}

Request body (version 3.2)

Content-Type: application/json

{
    PlatformID : int,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string
    ApplicationHostID : int, // can be null
    IsApplicationHost : bool
}

Request body details

• PlatformID:(required) ID of the managed system platform.
• ContactEmail: Max string length is 1000.
• Description: Max string length is 255.
• Port: (optional) The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds, default: 30) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: (default: 0/None) Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: (default: 0) ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: (default: 0) ID of the default DSS key rule assigned to managed accounts created under this managed system. Can be set when Platform.DSSFlag is true.
• LoginAccountID: (optional) ID of the functional account used for SSH Session logins. Can be set if the Platform.LoginAccountFlag is true.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false. Can be set if Platform.AutoManagementFlag is true.
  • FunctionalAccountID: (required if AutoManagementFlag is true) ID of the functional account used for local managed account password changes. FunctionalAccount.PlatformID must either match the ManagedSystem.PlatformID or be a domain platform (AD, LDAP).
  • ElevationCommand: (optional) Elevation command to use. Can be set if Platform.SupportsElevationFlag is true (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: (default: first) The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999, required if ChangeFrequencyType is xdays) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59, default: 23:30) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: (default: null, required when Platform.RequiresApplicationHost = true) Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: (default: false) true if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be nullIs
        ApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

• 200 - Request successful - Asset was already managed. Managed System in response body.
• 201 - Request successful - Asset is now managed. Managed System in response body.

POST Databases/{databaseID}/ManagedSystems

Purpose

Creates a managed system for the database referenced by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

databaseID: ID of the database.

Request body

Content-Type: application/json

{
    ContactEmail : string,
    Description : string,
    Timeout : short,
    PasswordRuleID : int,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,

    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
}

Request body details

• ContactEmail: Max string length is 1000.
• Description: Max string length is 255.
• Timeout: (seconds, default: 30) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• PasswordRuleID: (default: 0) ID of the default password rule assigned to managed accounts created under this managed system.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false. Can be set if Platform.AutoManagementFlag is true.
  • FunctionalAccountID: (required if AutoManagementFlag is true) ID of the functional account used for local managed account password changes. FunctionalAccount.PlatformID must either match the ManagedSystem.PlatformID or be a domain platform (AD, LDAP).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: (default: first) The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999, required if ChangeFrequencyType is xdays) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59, default: 23:30) UTC time of day scheduled password changes take place.

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int

        HostName : string

        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null

        ManagedSystemID : int,
        EntityTypeID: int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,

        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be nullIs
        ApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

• 200 - Request successful - Asset was already managed. Managed System in response body.
• 201 - Request successful - Asset is now managed. Managed System in response body.

POST Workgroups/{id}/ManagedSystems

Purpose

Creates a managed system in the Workgroup referenced by ID.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

id: ID of the Workgroup.

version: (optional, default: 3.0) Request body model version (3.0, 3.1, 3.2, 3.3).

Request body (version 3.0)

Content-Type: application/json

{
    EntityTypeID : int,

    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null

    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    AccountNameFormat : int,
    OracleInternetDirectoryID : guid, // can be null
    OracleInternetDirectoryServiceName : string,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    AccessURL : string
}

Request body (version 3.1)

Content-Type: application/json

{
    EntityTypeID : int,

    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null

    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    AccountNameFormat : int,
    OracleInternetDirectoryID : guid, // can be null
    OracleInternetDirectoryServiceName : string,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string,
    AccessURL : string
}

Request body (version 3.2)

Content-Type: application/json

{
    EntityTypeID : int,
    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null
    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    AccountNameFormat : int,
    OracleInternetDirectoryID : guid, // can be null
    OracleInternetDirectoryServiceName : string,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    ApplicationHostID : int, // can be null
    IsApplicationHost : bool,
    RemoteClientType : string,
    AccessURL : string
}

Request body (version 3.3)

Content-Type: application/json

{
    EntityTypeID : int,
    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null
    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    AccountNameFormat : int,
    OracleInternetDirectoryID : guid, // can be null
    OracleInternetDirectoryServiceName : string,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string,
    ApplicationHostID : int, // can be null
    IsApplicationHost : bool,
    AccessURL : string
}

Request body details

• EntityTypeID: (required) Type of entity being created.
• HostName: (required) Name of the host (applies to static asset, static database, directory, cloud). Max string length is 128 characters.
  • Static Asset: Asset name.
  • Static Database: Database host name.
  • Directory: Directory/domain name.
  • Cloud: Cloud system name.
• IPAddress: IPv4 address of the host (applies to static asset, static database). Max string length is 45.
• DnsName: DNS name of the host (applies to static asset, static database). Max string length is 255.
• InstanceName: Name of the database instance. Required when IsDefaultInstance is false (applies to static database only). Max string length is 100.
• IsDefaultInstance: True if the database instance is the default instance, otherwise false. Only platforms MS SQL Server and MySQL support setting this value to true (applies to static database only).
• Template: The database connection template (applies to static database only).
• ForestName: Name of the directory forest (required for Active Directory; optional for Entra ID). Max string length is 64.
• UseSSL (default: false) True to use an SSL connection, otherwise false (applies to directory only).
• PlatformID: (required) ID of the managed system platform.
• NetBiosName: The NetBIOS name of the host. Can be set if Platform.NetBiosNameFlag is true. Max string length is 15.
• ContactEmail: Max string length is 1000.
• Description: Max string length is 255.
• Port: (optional) The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds, default: 30) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: (default: 0/None) Enforcement mode for SSH host keys.
  • 0: None
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: (default: 0) ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: (default: 0) ID of the default DSS key rule assigned to managed accounts created under this managed system. Can be set when Platform.DSSFlag is true.
• LoginAccountID: (optional) ID of the functional account used for SSH session logins. Can be set if the Platform.LoginAccountFlag is true.
• AccountNameFormat: (Active Directory only, default: 0) Account name format to use:
  • 0: Domain and account. Use ManagedAccount.DomainName\ManagedAccount.AccountName.
  • 1: UPN. Use the managed account UPN.
  • 2: SAM. Use the managed account SAM account name.
• OracleInternetDirectoryID: The Oracle Internet Directory ID (applies to database entity types and Oracle platform only).
• OracleInternetDirectoryServiceName: (required when OracleInternetDirectoryID is set) The database service name related to the given OracleInternetDirectoryID (applies to database entity types and Oracle platform only). Max string length is 200.
• ReleaseDuration: (minutes: 1-525600, default: 120) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600, default: 525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600, default: 120) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: (default: false) True if password auto-management is enabled, otherwise false. Can be set if Platform.AutoManagementFlag is true.
  • FunctionalAccountID: (required if AutoManagementFlag is true) ID of the functional account used for local managed account password changes. FunctionalAccount.PlatformID must either match the ManagedSystem.PlatformID or be a directory platform (AD, LDAP).
  • ElevationCommand: (optional) Elevation command to use. Can be set if Platform.SupportsElevationFlag is true.
    • sudo
    • pbrun
    • pmrun
• CheckPasswordFlag: True to enable password testing, otherwise false.
• ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
• ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
• ApplicationHostID: (default: null, required when Platform.RequiresApplicationHost = true) Managed system ID of the target application host. Must be an ID of a managed system where IsApplicationHost = true.
• IsApplicationHost: (default: false) true if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• RemoteClientType: (default: None) The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• AccessURL: (default: default URL for the selected platform) The URL used for cloud access (applies to cloud systems only). Max string length is 2048.

Response body (when limit is not given)

Content-Type: application/json

{
    WorkgroupID : int,
    ManagedSystemID : int,
    EntityTypeID : int, 
    AssetID : int, // can be null
    DatabaseID : int, // can be null
    DirectoryID : int, // can be null
    CloudID : int, // can be null

    HostName : string,
    IPAddress : string,
    DnsName : string,
    InstanceName : string,
    IsDefaultInstance : bool, // can be null
    Template : string,
    ForestName : string,
    UseSSL : bool, // can be null
    AccountNameFormat : int,

    SystemName : string,
    PlatformID : int,
    NetBiosName : string,
    ContactEmail : string,
    Description : string,
    Port : int, // can be null
    Timeout : short,
    SshKeyEnforcementMode : int, // can be null
    PasswordRuleID : int,
    DSSKeyRuleID : int, // can be null
    LoginAccountID : int, // can be null
    AccountNameFormat : int,
    OracleInternetDirectoryID : guid, // can be null
    OracleInternetDirectoryServiceName : string,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    AutoManagementFlag : bool,
    FunctionalAccountID : int, // can be null
    ElevationCommand : string, // can be null
    CheckPasswordFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,
    RemoteClientType : string,
    ApplicationHostID : int, // can be null
    IsApplicationHost : bool,
    AccessURL : string
}

Response body details

• ManagedSystemID: ID of the managed system.
• AssetD: Asset ID; set if the managed system is an asset or a database.
• DatabaseID: Database ID; set if the managed system is a database.
• DirectoryID: Directory ID; set if the managed system is a directory.
• CloudID: Cloud system ID; set if the managed system is a cloud system.
• SystemName: Name of the related entity (asset, directory, database, or cloud).
• PlatformID: ID of the managed system platform.
• NetBiosName: (Managed domains only) Domain NetBIOS name. Setting this value will allow Password Safe to fall back to the NetBIOS name if needed.
• Port: The port used to connect to the host. If null and the related Platform.PortFlag is true, Password Safe uses Platform.DefaultPort for communication.
• Timeout: (seconds) Connection timeout. Length of time in seconds before a slow or unresponsive connection to the system fails.
• SshKeyEnforcementMode: Enforcement mode for SSH host keys.
  • 0: None.
  • 1: Auto. Auto accept initial key.
  • 2: Strict. Manually accept keys.
• PasswordRuleID: ID of the default password rule assigned to managed accounts created under this managed system.
• DSSKeyRuleID: ID of the default DSS key rule assigned to managed accounts created under this managed system.
• LoginAccountID: ID of the functional account used for SSH session logins.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • FunctionalAccountID: ID of the functional account used for local managed account password changes.
  • ElevationCommand: Elevation command to use (sudo, pbrun, pmrun).
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (see ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-90) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• RemoteClientType: The type of remote client to use.
  • None: No remote client.
  • EPM: Endpoint Privilege Management.
• ApplicationHostID: Managed system ID of the target application host. Must be an ID of a managed system whose IsApplicationHost = true.
• IsApplicationHost: True if the managed system can be used as an application host, otherwise false. Can be set when the Platform.ApplicationHostFlag = true, and cannot be set when ApplicationHostID has a value.
• AccessURL: The URL used for cloud access (applies to cloud systems only).

Response codes

200 - Request successful. Managed System in response body.

DELETE ManagedSystems/{id}

Purpose

Deletes a managed system by ID.

ℹ️

Note

DELETE ManagedSystems/{id} supports all managed system types: dynamic asset, static asset, dynamic database, static database, directory, and cloud.

Required permissions

Password Safe System Management (Read/Write).

URL parameters

id: ID of the managed system.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

Quick rule managed systems

GET QuickRules/{quickRuleID}/ManagedSystems

Purpose

Returns a list of managed systems by Quick Rule ID.

Required permissions

Read access to the Quick Rule.

URL parameters

quickRuleID: ID of the Quick Rule.

Request body

None.

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int
        HostName : string
        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null
        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response codes

200 – Request successful. Managed Systems in the response body.

PUT QuickRules/{quickRuleID}/ManagedSystems

Purpose

Updates the entire list of Managed Systems in a Quick Rule by removing all Managed System - Quick Rule filters and adding a new one with the Managed Systems referenced by ID.

Required permissions

Password Safe System Management (Read).

Read/Write access to the Quick Rule.

URL parameters

quickRuleID: ID of the Quick Rule.

Request body

Content-Type: application/json

{
    IDs: [ int, …]
}

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int
        HostName : string
        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null
        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response codes

200 – Request successful. Managed Systems in the response body.

POST QuickRules/{quickRuleID}/ManagedSystems/{systemID}

Purpose

Adds the Managed System referenced by ID to the Quick Rule by adding it to the first Managed System - Quick Rule filter found.

Required permissions

Password Safe System Management (Read).

Read/Write access to the Quick Rule.

URL parameters

quickRuleID: ID of the Quick Rule.

systemID: ID of the Managed System.

Request body

None.

Response body

Content-Type: application/json

[
    {
        WorkgroupID : int
        HostName : string
        IPAddress : string
        DNSName : string
        InstanceName : string
        IsDefaultInstance : bool // can be null
        Template : string
        ForestName : string
        UseSSL : bool // can be null
        ManagedSystemID : int,
        EntityTypeID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        Timeout : short,
        PlatformID: int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        AccountNameFormat : int,
        OracleInternetDirectoryID : guid, // can be null
        OracleInternetDirectoryServiceName : string,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response codes

200 – Request successful. Managed Systems in the response body.

DELETE QuickRules/{quickRuleID}/ManagedSystems/{systemID}

Purpose

Removes the Managed System referenced by ID from the Quick Rule by removing it from all Managed System - Quick Rule filters found.

⚠️

Important

A rule cannot be left in an invalid state. If removing the system would result in an empty filter, the filter itself will be removed. If there are no filters left in the rule, a "400 Bad Request" is returned.

• If you intend to replace all systems in the rule, see PUT QuickRules/{quickRuleID}/ManagedAccounts
• If you intend to delete the rule, see DELETE QuickRules/{id}

Required permissions

Read/Write access to the Quick Rule.

URL parameters

quickRuleID: ID of the Quick Rule.

systemID: ID of the Managed System.

Request body

None.

Response codes

200 – Request successful.

Smart Rule managed systems

GET SmartRules/{id}/ManagedSystems

Purpose

Returns a list of managed systems by Smart Rule ID.

Required permissions

• Read access to the Smart Rule referenced by ID.

URL parameters

id: ID of the Smart Rule.

Query parameters (optional)

• limit: (default: 100000) Number of records to return.
• offset: (default: 0) Number of records to skip before returning records (can be used only in conjunction with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[
    {
        ManagedSystemID : int,
        AssetID : int, // can be null
        DatabaseID : int, // can be null
        DirectoryID : int, // can be null
        CloudID : int, // can be null
        SystemName : string,
        PlatformID : int,
        NetBiosName : string,
        ContactEmail : string,
        Description : string,
        Port : int, // can be null
        Timeout : short,
        SshKeyEnforcementMode : int, // can be null
        PasswordRuleID : int,
        DSSKeyRuleID : int, // can be null
        LoginAccountID : int, // can be null
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        AutoManagementFlag : bool,
        FunctionalAccountID : int, // can be null
        ElevationCommand : string, // can be null
        CheckPasswordFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,
        RemoteClientType : string,
        ApplicationHostID : int, // can be null
        IsApplicationHost : bool,
        AccessURL : string
    },
    …
]

Response body (when limit is given)

Content-Type: application/json

{ 
    TotalCount : int,
    Data :
    [
        {
            ManagedSystemID : int,
            AssetID : int, // can be null
            DatabaseID : int, // can be null
            DirectoryID : int, // can be null
            CloudID : int, // can be null
            SystemName : string,
            PlatformID : int,
            NetBiosName : string,
            ContactEmail : string,
            Description : string,
            Port : int, // can be null
            Timeout : short,
            PasswordRuleID : int,
            DSSKeyRuleID : int, // can be null
            LoginAccountID : int, // can be null
            ReleaseDuration : int,
            MaxReleaseDuration : int,
            ISAReleaseDuration : int,
            AutoManagementFlag : bool,
            FunctionalAccountID : int, // can be null
            ElevationCommand : string, // can be null
            CheckPasswordFlag : bool,
            ChangePasswordAfterAnyReleaseFlag : bool,
            ResetPasswordOnMismatchFlag : bool,
            ChangeFrequencyType : string,
            ChangeFrequencyDays : int,
            ChangeTime : string,
            RemoteClientType : string,
            ApplicationHostID : int, // can be null
            IsApplicationHost : bool,
            AccessURL : string
        },
    …]
}

Response codes

200 - Request successful. Managed Systems in response body.

Nodes

Nodes represent the session monitoring agent nodes that can be used for establishing sessions.

GET nodes

Purpose

Returns a list of session monitoring agent nodes.

Query parameters

includeInactive: (optional, default: false) True to return all nodes including nodes that are inactive, otherwise False.

Request body

None.

Response body

Content-Type: application/json

[
    {
        NodeID: string,
        HostName: string,
        DisplayName: string,
        LastHeartbeat: DateTime, // can be null
        IsActive: bool,
    },
    …
]

Response body details

• NodeID: Node unique ID.
• HostName: Node host name.
• DisplayName: Node display name.
• LastHeartbeat: The date and time of the last session monitoring agent heartbeat from this node.
• IsActive: True if the session monitoring agent is considered active and running, otherwise false.

Response codes

200 - Request successful. Nodes in the response body.

Password policies

ℹ️

Note

Password policies are formerly known as password rules but the API remains PasswordRules to be compatible with earlier versions.

GET PasswordRules

Purpose

Returns a list of password rules.

Required permissions

Password Safe System Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {   
        PasswordRuleID : int, 
        Name : string, 
        Description : string, 
        MinimumLength : int, 
        MaximumLength : int,
        FirstCharacterRequirement : char, 
        LowercaseRequirement : char, 
        UppercaseRequirement : char, 
        NumericRequirement : char, 
        SymbolRequirement : char, 
        ValidLowercaseCharacters : char[], 
        ValidUppercaseCharacters : char[], 
        ValidSymbols : char[],
        EnabledProducts : int
    },
    …
]

Response body details

• FirstCharacterRequirement: The first character of the password must be:
  • C: Characters (alpha) only.
  • N: Numeric permitted, in addition to alpha characters.
  • A: Any character permitted.
• LowercaseRequirement: Lowercase character requirements:
• UppercaseRequirement: Uppercase character requirements:
• NumericRequirement: Numeric requirements:
• SymbolRequirement: Symbol requirements:
  • N: Not permitted.
  • P: Permitted, not required.
  • R: Required.
• EnabledProducts: The type of products to return:
  • 1: Password Safe.
  • 2: Secrets Safe.

Response codes

200 - Request successful. Password Rules in the response body.

400 - Enabled product not valid.

GET PasswordRules?enabledproducts={productName}

Purpose

Returns a list of password rules, with an optional parameter to return polices enabled for Password Safe or Secrets Safe.

Required permissions

Password Safe System Management (Read).

Query parameters

{string} The product name to select polices enabled for Password Safe or Secrets Safe:

• 1: PasswordSafe
• 2: SecretsSafe

Request body

None.

Response body

Content-Type: application/json

[
         {  
            PasswordRuleID : int, 
            Name : string, 
            Description : string, 
            MinimumLength : int, 
            MaximumLength : int,
            FirstCharacterRequirement : char, 
            LowercaseRequirement : char, 
            UppercaseRequirement : char, 
            NumericRequirement : char, 
            SymbolRequirement : char, 
            ValidLowercaseCharacters : char[], 
            ValidUppercaseCharacters : char[], 
            ValidSymbols : char[],
            EnabledProducts : int
         },
         …
]

Response body details

• FirstCharacterRequirement: The first character of the password must be:
  • C: Characters (alpha) only.
  • N: Numeric permitted, in addition to alpha characters.
  • A: Any character permitted.
• LowercaseRequirement: Lowercase character requirements:
• UppercaseRequirement: Uppercase character requirements:
• NumericRequirement: Numeric requirements:
• SymbolRequirement: Symbol requirements:
  • N: Not permitted.
  • P: Permitted, not required.
  • R: Required.
• EnabledProducts: The type of products to return:
  • 1: Password Safe.
  • 2: Secrets Safe.

Response codes

200 - Request successful. Password Rules in the response body.

400 - Enabled product not valid.

GET PasswordRules/{id}

Purpose

Returns a password rule by ID.

Required permissions

Password Safe System Management (Read).

URL parameters

id: ID of the password rule.

Request body

None.

Response body

Content-Type: application/json

{
    PasswordRuleID: int, 
    Name: string, 
    Description: string, 
    MinimumLength: int, 
    MaximumLength: int,
    FirstCharacterRequirement: char, 
    LowercaseRequirement: char, 
    UppercaseRequirement: char, 
    NumericRequirement: char, 
    SymbolRequirement: char, 
    ValidLowercaseCharacters: char[], 
    ValidUppercaseCharacters: char[], 
    ValidSymbols: char[],
    EnabledProducts : int
}

Response body details

• FirstCharacterRequirement: The first character of the password must be:
  • C: Characters (alpha) only.
  • N: Numeric permitted, in addition to alpha characters.
  • A: Any character permitted.
• LowercaseRequirement: Lowercase character requirements:
•  UppercaseRequirement: Uppercase character requirements:
•  NumericRequirement: Numeric requirements:
•  SymbolRequirement: Symbol requirements:
  • N: Not permitted.
  • P: Permitted, not required.
  • R: Required.
• EnabledProducts: The type of products to return:
  • 1: Password Safe.
  • 2: Secrets Safe.

Response codes

200 - Request successful. Password rules in the response body.

400 - Enabled product not valid.

Platforms

GET Platforms

Purpose

Returns a list of platforms for managed systems.

Required permissions

None.

Request body

None.

Response body

Content-Type: application/json

[
    {
        PlatformID : int,
        Name : string,
        ShortName : string,
        PortFlag : bool,
        DefaultPort : int, // can be null
        SupportsElevationFlag : bool,
        DomainNameFlag : bool,
        AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        ManageableFlag : bool,
        DSSFlag : bool,
        LoginAccountFlag : bool,
        DefaultSessionType : string // can be null,
        ApplicationHostFlag : bool,
        RequiresApplicationHost : bool,
        RequiresTenantID : bool,
        RequiresObjectID : bool,
        RequiresSecret : bool
    }
    …
]

Response body details

• PlatformID: Platform ID.
• Name: Platform name.
• ShortName: Platform short name.
• PortFlag: True if the platform supports setting a port, otherwise false.
• DefaultPort: The default port used when no port is given for managed systems of this platform.
• DomainNameFlag: True if the platform supports setting a domain name on a functional account of this platform, otherwise false.
• SupportsElevationFlag: True if the platform supports elevation, otherwise false.
• AutoManagementFlag: True if the platform supports password auto-management, otherwise false.
• DSSAutoManagementFlag: True if the platform supports DSS key auto-management, otherwise false.
• ManageableFlag: True if functional accounts can be created for the platform, otherwise false.
• DSSFlag: True if the platform supports DSS keys, otherwise false.
• LoginAccountFlag: True if the platform supports SSH login accounts, otherwise false.
• DefaultSessionType: The default type of session for the platform (RDP, SSH, or null).
• ApplicationHostFlag: true if the platform supports being used as a managed system application host, otherwise false.
• RequiresApplicationHost: true if the platform requires a target application host, otherwise false.
• RequiresTenantID: true if the platform requires a TenantID.
• RequiresObjectID: true if the platform requires an ObjectID.
• RequiresSecret: true if the platform requires a secret.

Response codes

200 – Request successful. Platforms in response body.

GET Platforms/{id}

Purpose

Returns a platform by ID for managed systems.

Required permissions

None.

URL parameters

id: ID of the platform.

Request body

None.

Response body

Content-Type: application/json

{
    PlatformID : int,
    Name : string,
    ShortName : string,
    PortFlag : bool,
    DefaultPort: int, // can be null
    SupportsElevationFlag : bool,
    DomainNameFlag: bool,
    AutoManagementFlag: bool,
    DSSAutoManagementFlag: bool,
    ManageableFlag: bool,
    DSSFlag: bool,
    LoginAccountFlag : bool,
    DefaultSessionType: string // can be null,
    ApplicationHostFlag : bool,
    RequiresApplicationHost : bool,
    RequiresTenantID : bool,
    RequiresObjectID : bool,
    RequiresSecret : bool
}

Response body details

• PlatformID: Platform ID.
• Name: Platform name.
• ShortName: Platform short name.
• PortFlag: True if the platform supports setting a port, otherwise false.
• DefaultPort: The default port used when no port is given for managed systems of this platform.
• DomainNameFlag: True if the platform supports setting a domain name on a functional account of this platform, otherwise false.
• SupportsElevationFlag: True if the platform supports elevation, otherwise false.
• AutoManagementFlag: True if the platform supports password auto-management, otherwise false.
• DSSAutoManagementFlag: True if the platform supports DSS key auto-management, otherwise false.
• ManageableFlag: True if functional accounts can be created for the platform, otherwise false.
• DSSFlag: True if the platform supports DSS keys, otherwise false.
• LoginAccountFlag: True if the platform supports SSH login accounts, otherwise false.
• DefaultSessionType: The default type of session for the platform (RDP, SSH, or null).
• ApplicationHostFlag: true if the platform supports being used as a managed system application host, otherwise false.
• RequiresApplicationHost: true if the platform requires a target application host, otherwise false.
• RequiresTenantID: true if the platform requires a TenantID.
• RequiresObjectID: true if the platform requires an ObjectID.
• RequiresSecret: true if the platform requires a secret.

Response codes

200 – Request successful. Platform in response body.

GET EntityTypes/{id}/Platforms

Purpose

Returns a list of Platforms by entity type ID.

Required permissions

None.

URL parameters

id: ID of the entity type.

Request body

None.

Response body

Content-Type: application/json

{
    PlatformID : int,
    Name : string,
    ShortName : string,
    PortFlag : bool,
    DefaultPort: int, // can be null
    SupportsElevationFlag : bool,
    DomainNameFlag: bool,
    AutoManagementFlag: bool,
    DSSAutoManagementFlag: bool,
    ManageableFlag: bool,
    DSSFlag: bool,
    LoginAccountFlag : bool,
    DefaultSessionType: string // can be null,
    ApplicationHostFlag : bool,
    RequiresApplicationHost : bool
    RequiresTenantID : bool,
    RequiresObjectID : bool,
    RequiresSecret : bool
}

Response body details

• PlatformID: Platform ID.
• Name: Platform name.
• ShortName: Platform short name.
• PortFlag: True if the platform supports setting a port, otherwise false.
• DefaultPort: The default port used when no port is given for managed systems of this platform.
• DomainNameFlag: True if the platform supports setting a domain name on a functional account of this platform, otherwise false.
• SupportsElevationFlag: True if the platform supports elevation, otherwise false.
• AutoManagementFlag: True if the platform supports password auto-management, otherwise false.
• DSSAutoManagementFlag: True if the platform supports DSS key auto-management, otherwise false.
• ManageableFlag: True if functional accounts can be created for the platform, otherwise false.
• DSSFlag: True if the platform supports DSS keys, otherwise false.
• LoginAccountFlag: True if the platform supports SSH login accounts, otherwise false.
• DefaultSessionType: The default type of session for the platform (RDP, SSH, or null).
• ApplicationHostFlag: true if the platform supports being used as a managed system application host, otherwise false.
• RequiresApplicationHost: true if the platform requires a target application host, otherwise false.
• RequiresTenantID: true if the platform requires a TenantID.
• RequiresObjectID: true if the platform requires an ObjectID.
• RequiresSecret: true if the platform requires a secret.

Response codes

200 – Request successful. Platform in response body.

Propagation action types

GET PropagationActionTypes

Purpose

Returns a list of propagation action types.

Required permissions

Password Safe Account Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
    PropagationActionTypeID : int,
    Name : string,
    }, ...    
]

Response codes

200 – Request successful. Propagation action types in the response body.

Propagation actions

GET PropagationActions

Purpose

Returns a list of propagation actions.

Required permissions

Password Safe Account Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
    PropagationActionID : int,
    PropagationActionTypeID : int,
    Name : string,
    Description : string, 
    }, ...    
]

Response codes

200 – Request successful. Propagation actions in the response body.

GET PropagationActions/{id}

Purpose

Returns a propagation action by ID.

Required permissions

Password Safe Account Management (Read).

Request body

None.

Response body

Content-Type: application/json

{
    PropagationActionID : int,
    PropagationActionTypeID : int,
    Name : string,
    Description : string,
    }

Response codes

200 – Request successful. Propagation action in the response body.

Managed account propagation actions

GET ManagedAccounts/{id}/PropagationActions/

Purpose

Returns a list of assigned propagation actions by managed account ID.

Required permissions

Password Safe Account Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
    PropagationActionID : int,
    PropagationActionTypeID : int,
    Name : string,
    Description : string,
    SmartRuleID : int? // can be null
    }, ...
]

Response codes

200 - Request successful. Propagation Actions in the response body.

POST ManagedAccounts/{id}/PropagationActions/{propagationActionID}

Purpose

Assigns a propagation action to the managed account referenced by ID.

Required permissions

Password Safe Account Management (Read/Write).

Request body (optional)

Content-Type: application/json

{
    SmartRuleID : int? // can be null
    }

Request body details

SmartRuleID : (optional) ID of the managed system-based Smart Rule to use for the propagation action assignment. If null or not given, uses scan data to determine propagation targets.

Response body

Content-Type: application/json

{
    PropagationActionID : int,
    PropagationActionTypeID : int,
    Name : string,
    Description : string,
    SmartRuleID : int? // can be null
    }

Response codes

200 - Propagation action was already assigned. Propagation action in the response body.

201 - Propagation action was assigned successfully. Propagation action in the response body.

DELETE ManagedAccounts/{id}/PropagationActions/

Purpose

Unassigns all propagation actions from the managed account by ID.

Required permissions

Password Safe Account Management (Read/Write).

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE ManagedAccounts/{id}/PropagationActions/{propagationActionID}

Purpose

Unassigns a propagation action from the managed account by ID.

Required permissions

Password Safe Account Management (Read/Write).

Request body

None.

Response body

None.

Response codes

200 - Request successful.

Quick rules

Quick Rules are a specialized Smart Rule for building a list of known managed accounts by ID. Smart Rules are considered Quick Rules when they contain at least one Managed Account Fields - Quick Group ID filter. Quick Rules can also be accessed via the SmartRules API endpoint.

ℹ️

Note

For more information on related, see:

• GET QuickRules/{quickRuleID}/ManagedAccounts
• PUT QuickRules/{quickRuleID}/ManagedAccounts
• POST QuickRules/{quickRuleID}/ManagedAccounts/{accountID}
• DELETE QuickRules/{quickRuleID}/ManagedAccounts/{accountID}

POST QuickRules

Purpose

Creates a new Quick Rule with the managed accounts or systems referenced by ID and Rule Type.

Required permissions

When RuleType=ManagedAccount:

• Password Safe Account Management (Read).
• Smart Rule Management - Managed Account (Read/Write).

When RuleType=ManagedSystem:

• Password Safe System Management (Read).
• Smart Rule Management - Managed System (Read/Write).

Request body

Content-Type: application/json

ℹ️

Note

AccountIDs are deprecated. Use IDs instead.

{
    IDs : [ int, …],
    Title : string,
    Category : string,
    Description : string,
    RuleType : string
}

Request body details

• AccountIDs: (deprecated) A list of managed account IDs to add to the Quick Rule.
• IDs: (required) A list of IDs to add to the Quick Rule.
• Title: (required) The title/name of the new Quick Rule. Must be unique across all Quick Rules and all Smart Rules. Max string length is 75.
• Category: (optional, default: Quick Rules) The category in which to place the Quick Rule. Max string length is 50.
• Description: (optional, default: ) The Quick Rule description.
• RuleType: (ManagedAccount, ManagedSystem, default: ManagedAccount)

Response body

Content-Type: application/json

{
    SmartRuleID : int,
    OrganizationID : string, // can be null
    Title : string,
    Description : string,
    Category : string,
    Status : int,
    LastProcessedDate : datetime,
    IsReadOnly : bool,
    RuleType : string
}

Response codes

201 – Request successful. Quick Rule in the response body.

GET QuickRules

Purpose

Returns a list of Quick Rules to which the current user has at least Read access.

Request body

None.

Response body

Content-Type: application/json

[
    {
        SmartRuleID : int,
        OrganizationID : string, // can be null
        Title : string,
        Description : string,
        Category : string,
        Status : int,
        LastProcessedDate : datetime,
        IsReadOnly : bool,
        RuleType : string
    },
    …
]

Response codes

200 – Request successful. Quick Rules in the response body.

GET QuickRules/{id}

Purpose

Returns a Quick Rule by ID.

Required permissions

Read access to the Quick Rule referenced by ID.

URL parameters

id: ID of the Quick Rule.

Request body

None.

Response body

Content-Type: application/json

{
    SmartRuleID : int,
    OrganizationID : string, // can be null
    Title : string,
    Description : string,
    Category : string,
    Status : int,
    LastProcessedDate : datetime,
    IsReadOnly : bool,
    RuleType : string
}

Response codes

200 – Request successful. Quick Rule in the response body.

GET QuickRules?title={title}

Purpose

Returns a Quick Rule by title.

In a multi-tenant environment, assumes global organization.

Required permissions

Read access to the Quick Rule referenced by title.

Query parameters

title: Title of the Quick Rule.

Request body

None.

Response body

Content-Type: application/json

{
    SmartRuleID : int,
    OrganizationID : string, // can be null
    Title : string,
    Description : string,
    Category : string,
    Status : int,
    LastProcessedDate : datetime,
    IsReadOnly : bool,
    RuleType : string
}

Response codes

200 – Request successful. Quick Rule in the response body.

GET Organizations/{orgID}/QuickRules?title={title}

Purpose

Returns a Quick Rule by organization ID and title.

Only valid in a mult-tenant environment.

Required permissions

Read access to the Quick Rule referenced by organization and title.

URL parameters

orgID: ID of the organization.

Query parameters

title: Title of the Quick Rule.

Request body

None.

Response body

Content-Type: application/json

{
    SmartRuleID : int,
    OrganizationID : string, // can be null
    Title : string,
    Description : string,
    Category : string,
    Status : int,
    LastProcessedDate : datetime,
    IsReadOnly : bool,
    RuleType : string
}

Response codes

200 – Request successful. Quick Rule in the response body.

DELETE QuickRules/{id}

Purpose

Deletes a Quick Rule by ID.

Required permissions

Read/Write access to the Quick Rule referenced by ID.

URL parameters

ID: ID of the Quick Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

DELETE QuickRules?title={title}

Purpose

Deletes a Quick Rule by title.

In a mult-tenant environment, assumes global organization.

Required permissions

Read/Write access to the Quick Rule referenced by title.

Query parameters

title: Title of the Quick Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

DELETE Organizations/{orgID}/QuickRules?title={title}

Purpose

Deletes a Quick Rule by organization ID and title. Only valid in a multi-tenant environment.

Required permissions

Read/Write access to the Quick Rule referenced by organization and title.

URL parameters

orgID: ID of the organization.

Query parameters

title: Title of the Quick Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Replay

POST pbsm/replay

Purpose

Creates a new replay session for a specified session token. The session token can be discovered using the sessions endpoints.

Query parameters

None.

Request body

Content-Type: application/json

{
    id: string, // Session Token from query to <base>/Sessions endpoint
    record_key: string, // RecordKey from query to <base>/Sessions endpoint
    protocol: string, // When session Type is 0 this should be RDP or for type 1 SSH
    headless: boolean // Must be set to true
}

Response body

Content-Type: application/json

{
    id: string, // ReplayID for this replay session
    token: string, // ReplayID for this replay session
    ticket: string, // Ticket value used internally
}

Response codes

• 200 – Request successful.
• 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
• 404 – Not found. The requested replay session was not found on the server.

GET pbsm/replay/{replayId}

Purpose

Displays the replay session details.

URL parameters

ReplayID: ID of the replay session returned from POST pbsm/replay.

Query parameters

• jpeg=(scale): Requests a JPEG image of the current RDP replay session scaled in size by the given scale.
• png=(scale): Requests a PNG image of the current RDP replay session scaled in size by the given scale.
• screen=1: Requests a text representation of the current SSH session.

Request body

None.

Response body

Content-Type: application/json

{
    tstamp: int, // Start time of the session in seconds
    end: int, // End time of the session in seconds
    offset: int, // Current offset of replay session in ms
    next: int, // Offset of next activity of replay session in ms
    speed: int, // Speed of replay session as a %
    eof: boolean, // Set to true when the end of the replay has been reached
    duration: int // Duration in ms of the replay session
}

Response codes

• 200 – Request successful.
• 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access.
• 404 – Not found. The requested replay session was not found on the server.

PUT pbsm/replay/{replayId}

Purpose

Controls the replay session status.

URL parameters

ReplayID: ID of the replay session returned from POST pbsm/replay.

Query parameters

None.

Request body

{
    speed: int, // Sets the replay speed of this session as a %
    offset: int, // Sets the offset of the replay cursor for this session in ms
    next: int // Requests the next changed frame based on the given % change
}

Response body

Content-Type: application/json

{
    tstamp: int, // Start time of the session in seconds
    end: int, // End time of the session in seconds
    offset: int, // Current offset of replay session in ms
    next: int, // Offset of next activity of replay session in ms
    speed: int, // Speed of replay session as a %
    eof: boolean, // Set to true when the end of the replay has been reached
    duration: int // Duration in ms of the replay session
}

Response codes

• 200 – Request successful.
• 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
• 404 – Not found. The requested replay session was not found on the server.

DELETE pbsm/replay/{replayId}

Purpose

Terminates the replay session.

URL parameters

ReplayID: ID of the replay session returned from POST pbsm/replay.

Query parameters

None.

Request body

None.

Response codes

• 200 – Request successful.
• 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
• 404 – Not found. The requested replay session was not found on the server.

Requests

GET Requests

Purpose

Lists requests for the current user.

Query parameters

• status: (optional, default: all) Status of requests to return.
  • all: Both active and pending requests.
  • active: Requests that have been approved (including auto-approved).
  • pending: Requests that have not yet been approved.
• queue: (optional, default: req): Type of request queue to return.
  • req: Requestor queue, returns requests available to the user as a requestor.
  • app: Approver queue, returns requests for an approver or requestor/approver that have either been approved by the user (active) or have not yet been approved (pending).

Request body

None.

Response body

Content-Type: application/json

[
    {
        RequestID: int,
        SystemID: int,
        SystemName: string,
        AccountID: int,
        AccountName: string,
        DomainName: string,
        AliasID: int,
        ApplicationID: int,
        RequestReleaseDate: date-formatted string,
        ApprovedDate: date-formatted string,
        ExpiresDate: date-formatted string,
        Status: string,
        AccessType: string,
        Reason: string
    },
    …
]

Response codes

• 200 – Request successful. Requests in the response body.
• 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
  • 4033 – Approver Only API or account. Only Approvers can access this API or account.

POST Requests

Purpose

Creates a new release request.

Required roles

• Requestor or requestor/approver role to managed account referenced by ID

Request body

Content-Type: application/json

{
    AccessType: string,
    SystemID: int,
    AccountID: int,
    ApplicationID: int, // can be null
    DurationMinutes : int,
    Reason : string,
    AccessPolicyScheduleID : int, // can be null
    ConflictOption : string,
    TicketSystemID : int,
    TicketNumber : string,
    RotateOnCheckin: bool
}

Request body details

• AccessType: (optional, default: View) The type of access requested (View, RDP, SSH, App).
  • View: View Password access.
  • RDP: RDP access (corresponds to POST Sessions SessionType RDP or rdpfile).
  • SSH: SSH access (corresponds to POST Sessions SessionType SSH).
  • App: Application access (corresponds to POST Sessions SessionType App or appfile).
• SystemID: (required) ID of the managed system to request.
• AccountID: (required) ID of the managed account to request.
• ApplicationID: (required when AccessType=App): ID of the application for an application-based request.
• DurationMinutes: (required: 1-525600) The request duration (in minutes).
• Reason: (optional) The reason for the request.
• AccessPolicyScheduleID: (optional) The schedule ID of an access policy to use for the request. If omitted, automatically selects the best schedule.
• ConflictOption: (optional) The conflict resolution option to use if an existing request is found for the same user, system, and account (reuse, renew). If omitted and a conflicting request is found, returns a 409 code (see below).
  • reuse: Returns an existing, approved request ID for the same user/system/account/access type (if one exists). If the request does not already exist, creates a new request using the request body details.
  • renew: Cancels any existing approved requests for the same user/system/account and creates a new request using the request body details.
• TicketSystemID: ID of the ticket system. If omitted, then default ticket system will be used.
• TicketNumber: Number of associated ticket. Can be required if ticket system is marked as required in the access policy used. Max string length is 20.
• RotateOnCheckin: (optional, default: true) True to rotate the credentials on check-in/expiry, otherwise false. This property can only be used if the access policy (either auto-selected or given in AccessPolicyScheduleID) supports it.

ℹ️

Note

In reference to RotateOnCheckin, If the Managed Account given in AccountID does not rotate the credentials after check-in/expiry, this setting is ignored.

ℹ️

Note

For more information, see the Allow API Rotation Override access policy setting under View access.

Response body

{
    RequestID: int
}

Response codes

• 200 – Existing request is being reused. Existing request ID in the response body.
• 201 – Request successful. Request ID in the response body.
• 403 – User does not have permissions to request the indicated account or the account does not have API access enabled. Response body contains a status code indicating the reason for this forbidden access:
  • 4031 – User does not have permission to request the account or the account is not valid for the system.
  • 4033 – Approver Only API or account. Only Approvers can access this API or account.
  • 4035 - Not enough Approvers configured to approve a request.
• 409 – Conflicting request exists. This user or another user has already requested a password for the specified account within the next window.

POST Aliases/{aliasId}/Requests

Purpose

Creates a new release request using an alias.

Required roles

Requestor or requestor/approver role to managed account referenced by the alias.

URL parameters

aliasId: ID of the managed account alias.

Request body

Content-Type: application/json

{
    AccessType: string,
    DurationMinutes : int,
    Reason : string,
    AccessPolicyScheduleID : int, // can be null
    ConflictOption : string,
    TicketSystemID : int,
    TicketNumber : string,
    RotateOnCheckin: bool
}

Request body details

• AccessType: (optional, default: View) The type of access requested (View, RDP, SSH, App).
  • View: View password access.
  • RDP: RDP access (corresponds to POST Sessions SessionType RDP or rdpfile).
  • SSH: SSH access (corresponds to POST Sessions SessionType SSH).
• DurationMinutes: (required: 1-525600): The request duration (in minutes).
• Reason: (optional) The reason for the request.
• AccessPolicyScheduleID: (optional) The schedule ID of an access policy to use for the request. If omitted, automatically selects the best schedule.
• ConflictOption: (optional) The conflict resolution option to use if an existing request is found for the same user, system, and account (reuse, renew). If omitted and a conflicting request is found, returns a 409 (see below).
  • reuse: Return an existing, approved request ID for the same user/system/account/access type (if one exists). If the request does not already exist, creates a new request using the request body details.
  • renew: Cancel any existing approved requests for the same user/system/account and create a new request using the request body details.
• TicketSystemID: ID of the ticket system. If omitted then default ticket system is used.
• TicketNumber: Number of associated ticket. Can be required if ticket system is marked as required in the access policy used. Max string length is 20.
• RotateOnCheckin: (optional, default: true) True to rotate the credentials on check-in/expiry, otherwise false. This property can only be used if the access policy (either auto-selected or given in AccessPolicyScheduleID) supports it. If the managed account given in AccountID does not rotate the credentials after check-in/expiry, this setting is ignored.

ℹ️

Note

For more information, see the Allow API Rotation Override access policy setting under View access.

Response body

{
    RequestID: int
}

Response codes

• 200 – Existing request is being reused. Existing request ID in the response body.
• 201 – Request successful. Request ID in the response body.
• 403 – User does not have permissions to request the indicated alias or the account referenced by the alias does not have API access enabled. Response body contains a status code indicating the reason for this forbidden access:
  • 4031 – User does not have permission to request the account or the account is not valid for the system.
  • 4033 – Approver Only API or account. Only Approvers can access this API or account.
  • 4035 - Not enough approvers configured to approve a request.
• 409 – Conflicting request exists. This user or another user has already requested a password for the specified account within the next window.

PUT Requests/{id}/Checkin

Alternate URI (deprecated)

PUT Requests/Release/{id}

Purpose

Checks-in/releases a request before it has expired.

Required roles

Requestor role to managed account referenced by the request.

URL parameters

id: ID of the request to check-in/release.

Request body

Content-Type: application/json

{
    Reason : string
}

Request body details

Reason: (optional) A reason or comment why the request is being released. Max string length is 1000.

Response body

None.

Response codes

• 204 – Request successful. No content in body.
• 403 – User does not have permissions to release the indicated request or the associated account does not have API access enabled. Message or status code in response body:
  • 4031 – User does not have permission to release a password.
  • 4034 – Request is not yet approved.

PUT Requests/{id}/Approve

Purpose

Approves a pending request.

Required roles

Approver or requestor/approver role to managed account referenced by the request.

URL parameters

id: ID of the request to approve.

Request body

Content-Type: application/json

{
    Reason : string
}

Request body details

Reason: (optional) A reason or comment why the request is being approved. Max string length is 1000.

Response body

None.

Response codes

• 204 – Request successful. No content in body.
• 403 – User does not have permissions to approve the indicated request or the associated account does not have API access enabled. Message or status code in response body:
  • 4033 – Approver only - User cannot approve his or her own request.
  • 4036 – Request has been approved already.

PUT Requests/{id}/Deny

Purpose

Denies/cancels an active or pending request.

Required roles

Approver or requestor/approver role to managed account referenced by the request.

URL parameters

id: ID of the request to deny/cancel.

Request body

Content-Type: application/json

{
    Reason : string
}

Request body details

Reason: (optional) A reason or comment why the request is being denied/cancelled. Max string length is 1000.

Response body

None.

Response codes

• 204 – Request successful. No content in body.
• 403 – User does not have permissions to deny the indicated request or the associated account does not have API access enabled. Message or status code in response body:
• 4033 – Approver only - User cannot deny his or her own request.

PUT Requests/{id}/RotateOnCheckin

Purpose

Updates a request to rotate the credentials on check-in/expiry.

ℹ️

Note

If POST Requests RotateOnCheckin=false, this updates the request to true. If POST Requests RotateOnCheckin=true, the request is not modified.

Requirements

• Current user must be the owner of the request.
• Request must not be cancelled or expired.

URL parameters

id: ID of the request to update.

Request body

None.

Response body

None.

Response codes

204 – Request successful. No content in body.

Request termination

POST ManagedAccounts/{managedAccountID}/Requests/Terminate

Purpose

Terminates all active requests by managed account ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

managedAccountID: ID of the managed account.

Request body

Content-Type: application/json

{
    Reason : string
}

Request body details

Reason: (optional) A reason or comment why the requests are being terminated. Max string length is 1000.

Response body

None.

Response codes

204 – Termination successful. No content in body.

POST ManagedSystems/{managedSystemID}/Requests/Terminate

Purpose

Terminates all active requests by managed system ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

managedSystemID: ID of the managed system.

Request body

Content-Type: application/json

{
    Reason : string
}

Request body details

Reason: (optional) A reason or comment why the requests are being terminated. Max string length is 1000.

Response body

None.

Response codes

204 – Termination successful. No content in body.

POST Users/{userID}/Requests/Terminate

Purpose

Terminates all active requests by requestor user ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

userID: ID of the requestor user.

Request body

Content-Type: application/json

{
    Reason : string
}

Request body details

Reason: (optional) A reason or comment why the requests are being terminated. Max string length is 1000.

Response body

None.

Response codes

204 – Termination successful. No content in body.

Request sets

Request sets are a grouping of requests to the same system and account with different access types (i.e. View and RDP). Requests in a request set are also accessible individually via GET requests.

Quick navigation

• GET RequestSets
• POST RequestSets

GET RequestSets

Purpose

Lists request sets for the current user.

Query parameters

status: (optional, default: all) Status of request sets to return (all, active, pending).

Request body

None.

Response body

Content-Type: application/json

[
    {
        RequestSetID: string,
        Requests:
        [
            {
                RequestID: int,
                RequestorName: string,
                SystemID: int,
                SystemName: string,
                AccountID: int,
                AccountName: string,
                DomainName: string,
                ApplicationID: int, // can be null,
                AliasID: int, // can be null
                RequestReleaseDate: date-formatted string,
                ApprovedDate: date-formatted string,
                CanceledDate: date-formatted string,
                ExpiresDate: date-formatted string,
                Status: string,
                AccessType: string,
                ApplicationID: int,
                Reason: string
            },
            …
        ]
    },
    …
]

Response codes

• 200 – Request successful. Requests in the response body.
• 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
  • 4033 – Approver Only API or account. Only Approvers can access this API or account.

POST RequestSets

Purpose

Creates a new release request set.

Required roles

• Requestor or Requestor/Approver role to managed account referenced by ID.
• Information Systems Administrator (ISA) role access.

Request body

Content-Type: application/json

{
    AccessTypes: [ string, … ],
    SystemID: int,
    AccountID: int,
    ApplicationID: int, // can be null,
    DurationMinutes : int,
    Reason : string,
    TicketSystemID : int,
    TicketNumber : string
}

Request body details

• AccessTypes: (at least two are required) A list of the types of access requested (View, RDP, SSH, App).
• SystemID: (required) ID of the managed system to request.
• AccountID: (required) ID of the managed account to request.
• ApplicationID: (required when an AccessType is App) ID of the application to request.
• DurationMinutes: (required) The request duration (in minutes).
• Reason: (optional) The reason for the request.
• TicketSystemID: ID of the ticket system. If omitted then default ticket system is used.
• TicketNumber: Number of associated ticket. Can be required if ticket system is marked as required in the access policy used. Max string length is 20.

Response body

Content-Type: application/json

{
    RequestSetID: string,
    Requests:
    [
        {
            RequestID: int,
            SystemID: int,
            SystemName: string,
            AccountID: int,
            AccountName: string,
            DomainName: string,
            ApplicationID: int, // can be null
            AliasID: int,
            RequestReleaseDate: date-formatted string,
            ApprovedDate: date-formatted string,
            ExpiresDate: date-formatted string,
            Status: string,
            AccessType: string
        },
        …
    ]
}

Response codes

• 201 – Request successful. Request set in the response body.
• 403 – User does not have permissions to perform a request for the indicated account or the account does not have API access enabled. Response body contains a status code indicating the reason for this forbidden access:
  • 4031 – User does not have permission to request the account or the account is not valid for the system.
  • 4033 – Approver Only API or account. Only Approvers can access this API or account.
  • 4035 - Not enough approvers configured to approve a request.
• 409 – Conflicting request exists. Another user has already requested a password for the specified account within the next window.

Roles

(i.e. requestor, approver, credentials manager, etc.)

GET Roles

Purpose

Returns a list of Password Safe roles.

Required permissions

Password Safe Role Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        RoleID : int,
        Name : string
    },
    …
]

Response codes

200 – Request successful. Roles in the response body.

User group roles

GET UserGroups/{userGroupId}/SmartRules/{smartRuleId}/Roles

Purpose

Returns a list of roles for the user group and Smart Rule referenced by ID.

Required permissions

• User Accounts Management (Read)
• Password Safe Role Management (Read).

URL parameters

• userGroupId: ID of the user group.
• smartRuleId: ID of the Smart Rule.

Request body

None.

Response body

Content-Type: application/json

[
    {
        RoleID : int,
        Name : string
    },
    …
]

Response codes

200 – Request successful. Roles in the response body.

POST UserGroups/{userGroupId}/SmartRules/{smartRuleId}/Roles

Purpose

Sets Password Safe roles for the user group and Smart Rule referenced by ID.

Required permissions

• User Accounts Management (Read/Write).
• Password Safe Role Management (Read/Write).

URL parameters

• userGroupId: ID of the user group.
• smartRuleId: ID of the Smart Rule.

Request body

Content-Type: application/json

{
    Roles : 
    [
        {
            RoleID : int
        },
        …
    ],
    AccessPolicyID : int
}

Request body details

• Roles: (required) Zero or more roles to set on the UserGroup-SmartRule.
• AccessPolicyID: The access policy ID to set on the UserGroup-SmartRule. Required when the Requestor or Requestor/Approver role is set.

Response body

None.

Response codes

204 – Request successful. No content in body.

DELETE UserGroups/{userGroupId}/SmartRules/{smartRuleId}/Roles

Purpose

Deletes all Password Safe roles for the user group and Smart Rule referenced by ID.

Required permissions

• User Accounts Management (Read/Write).
• Password SafeRole Management (Read/Write).

URL parameters

• userGroupId: ID of the user group.
• smartRuleId: ID of the Smart Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Sessions

GET Sessions

Purpose

Returns a list of sessions.

ℹ️

Note

The maximum number of sessions returned is 100,000.

Required permissions

A member of the Administrators group, or ISA or auditor role to at least one asset Smart Rule.

Query parameters (optional)

• status: Session status - A single value or comma-delimited list of values:
  • 0: Not Started
  • 1: In Progress
  • 2: Completed
  • 5: Locked
  • 7: Terminated (deprecated)
  • 8: Logged Off
  • 9: Disconnected (RDP only)
• userID: ID of the user that requested the session

Request body

None.

Response body

Content-Type: application/json

[
    {
        SessionID : int, 
        UserID : int,
        NodeID : string, 
        Status : int,
        ArchiveStatus : int, 
        Protocol : int, 
        StartTime : date, 
        EndTime : date, 
        Duration : int, 
        AssetName : string,
        ManagedSystemID : int, // can be null
        ManagedAccountID : int, 
        ManagedAccountName : string, 
        RecordKey : string,
        Token : string
    },
    …
]

Response body details

• SessionID: ID of the Session.
• UserID: ID of the user that requested the session.
• NodeID: ID of the Session Node.
• Status: Session status
  • 0: Not Started
  • 1: In Progress
  • 2: Completed
  • 5: Locked
  • 7: Terminated (deprecated)
  • 8: Logged Off
  • 9: Disconnected (RDP only)
• ArchiveStatus: Session archive status (applicable only when Session Archiving is enabled and configured)
  • 0: Not Archived
  • 1: Archived
  • 2: Restoring (from Archive Repository)
  • 3: Archiving (from Node)
  • 4: Session Not Found (in Archive Repository)
  • 5: Archive Repository Offline/Inaccessible
  • 6: Unknown
• Protocol: Session protocol
  • 0: RDP
  • 1: SSH
• StartTime: Start date/time of the session.
• EndTime: End date/time of the session.
• Duration: Session duration (seconds).
• AssetName: Name of the target Managed System.
• ManagedSystemID: ID of the target Managed System.
• ManagedAccountID: ID of the target Managed Account.
• ManagedAccountName: Name of the target Managed Account.
• RecordKey: The Record Key used for Session replay.
• Token: The Token used for Session replay.

Response codes

200 – Request successful. Sessions in the response body.

GET Sessions/{id}

Purpose

Returns a session by ID.

Required permissions

A member of the Administrators group, or ISA or auditor role to at least one asset Smart Rule.

URL parameters

id: ID of the session.

Request body

None.

Response body

Content-Type: application/json

{
    SessionID : int, 
    UserID : int,
    NodeID : string, 
    Status : int,
    ArchiveStatus : int, 
    Protocol : int, 
    StartTime : date, 
    EndTime : date, 
    Duration : int, 
    AssetName : string,
    ManagedSystemID : int,
    ManagedAccountID : int, 
    ManagedAccountName : string, 
    RecordKey : string,
    Token : string
}

Response body details

• SessionID: ID of the Session.
• UserID: ID of the user that requested the session.
• NodeID: ID of the Session Node.
• Status: Session status
  • 0: Not Started
  • 1: In Progress
  • 2: Completed
  • 5: Locked
  • 7: Terminated (deprecated)
  • 8: Logged Off
  • 9: Disconnected (RDP only)
• ArchiveStatus: Session archive status (applicable only when Session Archiving is enabled and configured)
  • 0: Not Archived
  • 1: Archived
  • 2: Restoring (from Archive Repository)
  • 3: Archiving (from Node)
  • 4: Session Not Found (in Archive Repository)
  • 5: Archive Repository Offline/Inaccessible
  • 6: Unknown
• Protocol: Session protocol
  • 0: RDP
  • 1: SSH
• StartTime: Start date/time of the session.
• EndTime: End date/time of the session.
• Duration: Session duration (seconds).
• AssetName: Name of the target Managed System.
• ManagedSystemID: ID of the target Managed System.
• ManagedAccountID: ID of the target Managed Account.
• ManagedAccountName: Name of the target Managed Account.
• RecordKey: The Record Key used for Session replay.
• Token: The Token used for Session replay.

Response codes

200 – Request successful. Sessions in the response body.

POST Requests/{requestID}/Sessions

Purpose

Create a new session for the given release.

Requirements

Must be the owner of the request ID.

URL parameters

requestID: ID of the request for which to create a session.

Request body

Content- Type: application/json

{
    SessionType : string,
    NodeID : string
}

Request body details

• SessionType: (required) The type of session to create (SSH or sshticket, RDP or rdpticket, rdpfile, app, or appfile).
• NodeID: (optional) ID of the node that should be used to establish the session. If NodeID is not given or if the Remote Session Proxy feature is disabled, uses the local node.

Response body (SSH or sshticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    TicketAtHost : string, 
    Link : string, 
    Command : string,
    SessionID : int,
    NodeID : string
}

Response body (RDP or rdpticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    SessionID : int,
    NodeID : string
}

Response body (rdpfile)

RDP File as an attachment.

Response body (app – when the target system is Unix- or ssh-based)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    TicketAtHost : string, 
    Link : string, 
    Command : string,
    SessionID : int,
    NodeID : string
}

Response body (app – when the target system is Windows- or rdp-based)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string,
    SessionID : int,
    NodeID : string
}

Response body (appfile)

RDP File as an attachment.

Response body details

• ID: The Session Token (same as Ticket).
• Ticket: The Session Token (same as ID).
• Host: The target Host Name.
• Port: The target Host Port.
• TicketAtHost: Formatted value: {Ticket}@{Host}
• Link: Formatted ssh link - ssh://{Ticket}@{Host}:{Port}
• Command: Formatted ssh command: ssh -p {Port} {Ticket}@{Host}
• SessionID: ID of the Session.
• NodeID: ID of the Session Node.

Response codes

• 201– Request successful. Session details or RDP file in the response body.
• 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
• 4034 – Request is not yet approved.

POST Sessions/Admin

Purpose

Create a new admin session.

Required roles

Password Safe Admin Session (Read/Write).

Request body

Content-Type: application/json

{
    SessionType : string, 
    HostName : string, 
    Port : int, // can be null 
    DomainName : string, 
    UserName : string, 
    Password : string, 
    Reason : string, 
    Resolution : string, 
    RDPAdminSwitch : bool, 
    SmartSizing : bool, 
    NodeID : string,
    Record : bool
}

Request body details

• SessionType: (required) The type of session to create (SSH or sshticket, RDP or rdpticket, or rdpfile)
• HostName: (required) Name or IP of the target host. Max string length is 128.
• Port: (optional, default: ) Port to use for the connection.
• DomainName: (optional) The domain name of the user. Max string length is 50.
• UserName: (required) The username. Max string length is 200.
• Password: (required) The password.
• Reason: (optional) The reason for the session.
• Resolution (RDP-only): (optional, default: ) The default resolution (i.e 1024x768 or Maximized). Max string length is 50.
• RDPAdminSwitch (RDP-only): (optional, default: false) True to use the RDP /admin switch, otherwise false.
• SmartSizing (RDP-only): (optional, default: false) True to use RDP Smart Sizing, otherwise false. Applies only when SessionType=rdpfile.
• NodeID: (optional) ID of the node that should be used to establish the Session. If NodeID is not given or if the Remote Session Proxy feature is disabled, uses the local node.
• Record: (optional, default: true) True to record the Session, otherwise false. Ignored and always recorded if the Global Setting Hide Record Checkbox for Admin Sessions is enabled.

Response body (SSH or sshticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string, 
    TicketAtHost : string, 
    Link : string, 
    Command : string, 
    SessionID : int, 
    NodeID : string 
}

Response body (RDP or rdpticket)

Content-Type: application/json

{
    ID : string, 
    Ticket : string, 
    Host : string, 
    Port : string, 
    SessionID : int, 
    NodeID : string 
}

Response body (rdpfile)

RDP file as an attachment.

Response body details

• ID: The Session Token (same as Ticket).
• Ticket: The Session Token (same as ID).
• Host: The target Host Name.
• Port: The target Host Port.
• TicketAtHost: Formatted value: {Ticket}@{Host}
• Link: Formatted ssh link - ssh://{Ticket}@{Host}:{Port}
• Command: Formatted ssh command: ssh -p {Port} {Ticket}@{Host}
• SessionID: ID of the Session.
• NodeID: ID of the Session Node.

Response codes

201 – Request successful. Session details or RDP file in the response body.

403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access.

Session locking

POST Sessions/{sessionID}/Lock

Purpose

Locks an active session.

Required permissions

One of:

• Password Safe API Global Quarantine (Read/Write)
• Password Safe Active Session Reviewer Role, ISA Role, or a member of BeyondInsight Administrators group.

URL parameters

sessionID: ID of the session.

Request body

None.

Response body

None.

Response codes

204 – Lock successful. No content in body.

POST ManagedAccounts/{managedAccountID}/Sessions/Lock

Purpose

Locks all active sessions by managed account ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

managedAccountID: ID of the managed account.

Request body

None.

Response body

None.

Response codes

204 – Lock successful. No content in body.

POST ManagedSystems/{managedSystemID}/Sessions/Lock

Purpose

Locks all active Sessions by managed system ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

managedSystemID: ID of the managed system.

Request body

None.

Response body

None.

Response codes

204 – Lock successful. No content in body.

Session termination

POST Sessions/{sessionID}/Terminate

Purpose

Terminates an active session.

Required permissions

One of:

• Password Safe API Global Quarantine (Read/Write)
• Password Safe Active Session Reviewer Role, ISA Role, or a member of BeyondInsight Administrators group.

URL parameters

sessionID: ID of the session to terminate.

Request body

None.

Response body

None.

Response codes

204 – Termination successful. No content in body.

POST ManagedAccounts/{managedAccountID}/Sessions/Terminate

Purpose

Terminates all active sessions by managed account ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

managedAccountID: ID of the managed account.

Request body

None.

Response body

None.

Response codes

204 – Termination successful. No content in body.

POST ManagedSystems/{managedSystemID}/Sessions/Terminate

Purpose

Terminates all active sessions by managed system ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

managedSystemID: ID of the managed system.

Request body

None.

Response body

None.

Response codes

• 204 – Termination successful. No content in body.

Synced accounts

Synced accounts are managed accounts subscribed/synced to another managed account.

GET ManagedAccounts/{id}/SyncedAccounts

Purpose

Returns a list of subscribed/synced managed accounts by managed account ID.

Required permissions

Password Safe Account Management (Read).

URL parameters

id: ID of the parent managed account.

Request body

None.

Response body

Content-Type: application/json

[
    {
        ManagedAccountID : int,
        ManagedSystemID : int,
        DomainName : string,
        AccountName : string,
        DistinguishedName : string,
        PasswordFallbackFlag : bool,
        LoginAccountFlag : bool,
        Description : string,
        PasswordRuleID : int,
        ApiEnabled : bool,
        ReleaseNotificationEmail : string,
        ChangeServicesFlag : bool,
        RestartServicesFlag : bool,
        ReleaseDuration : int,
        MaxReleaseDuration : int,
        ISAReleaseDuration : int,
        MaxConcurrentRequests : int,

        AutoManagementFlag : bool,
        DSSAutoManagementFlag : bool,
        CheckPasswordFlag : bool,
        ResetPasswordOnMismatchFlag : bool,
        ChangePasswordAfterAnyReleaseFlag : bool,
        ChangeFrequencyType : string,
        ChangeFrequencyDays : int,
        ChangeTime : string,

        ParentAccountID : int, // can be null
        IsSubscribedAccount : bool,
        LastChangeDate : datetime, // can be null
        NextChangeDate : datetime, // can be null
        IsChanging : bool,
        ChangeState : int,
        UseOwnCredentials : bool,
        ChangeIISAppPoolFlag : bool,
        RestartIISAppPoolFlag : bool,
        WorkgroupID : int, // can be null

        ChangeWindowsAutoLogonFlag : bool,
        ChangeComPlusFlag : bool,
        ChangeDComFlag : bool,
        ChangeSComFlag : bool,    
    },
    …
]

Response body details

• DomainName: The domain name for a domain-type account.
• AccountName: The name of the account.
• DistinguishedName: The distinguished name of an LDAP managed account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled: True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 is unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.

Response codes

200 – Request successful. Linked Managed Account in the response body.

POST ManagedAccounts/{id}/SyncedAccounts/{syncedAccountID}

Purpose

Subscribes/syncs a managed account to the managed account referenced by ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• id: ID of the parent managed account.
• syncedAccountID: ID of the synced managed account.

Request body

None.

Response body

Content-type: application/json

{
    ManagedAccountID : int,
    ManagedSystemID : int,
    DomainName : string,
    AccountName : string,
    DistinguishedName : string,
    PasswordFallbackFlag : bool,
    LoginAccountFlag : bool,
    Description : string,
    PasswordRuleID : int,
    ApiEnabled : bool,
    ReleaseNotificationEmail : string,
    ChangeServicesFlag : bool,
    RestartServicesFlag : bool,
    ReleaseDuration : int,
    MaxReleaseDuration : int,
    ISAReleaseDuration : int,
    MaxConcurrentRequests : int,

    AutoManagementFlag : bool,
    DSSAutoManagementFlag : bool,
    CheckPasswordFlag : bool,
    ResetPasswordOnMismatchFlag : bool,
    ChangePasswordAfterAnyReleaseFlag : bool,
    ChangeFrequencyType : string,
    ChangeFrequencyDays : int,
    ChangeTime : string,

    ParentAccountID : int, // can be null
    IsSubscribedAccount : bool,
    LastChangeDate : datetime, // can be null
    NextChangeDate : datetime, // can be null
    IsChanging : bool,
    ChangeState : int,
    UseOwnCredentials : bool,
    ChangeIISAppPoolFlag : bool,
    RestartIISAppPoolFlag : bool,
    WorkgroupID : int, // can be null

    ChangeWindowsAutoLogonFlag : bool,
    ChangeComPlusFlag : bool,
    ChangeDComFlag : bool,
    ChangeSComFlag : bool,        
}

Response body details

• AccountName: The name of the account.
• PasswordFallbackFlag: True if failed DSS authentication can fall back to password authentication, otherwise false.
• LoginAccountFlag: True if the account should use the managed system login account for SSH sessions, otherwise false.
• Description: A description of the account.
• PasswordRuleID: ID of the password rule assigned to this managed account.
• ApiEnabled:True if the account can be requested through the API, otherwise false.
• ReleaseNotificationEmail: Email address used for notification emails related to this managed account.
• ChangeServicesFlag: True if services run as this user should be updated with the new password after a password change, otherwise false.
• RestartServicesFlag: True if services should be restarted after the run as password is changed (ChangeServicesFlag), otherwise false.
• ReleaseDuration: (minutes: 1-525600) Default release duration.
• MaxReleaseDuration: (minutes: 1-525600) Default maximum release duration.
• ISAReleaseDuration: (minutes: 1-525600) Default Information Systems Administrator (ISA) release duration.
• MaxConcurrentRequests: (0-999, 0 means unlimited) Maximum number of concurrent password requests for this account.
• AutoManagementFlag: True if password auto-management is enabled, otherwise false.
  • DSSAutoManagementFlag: True if DSS key auto-management is enabled, otherwise false.
  • CheckPasswordFlag: True to enable password testing, otherwise false.
  • ChangePasswordAfterAnyReleaseFlag: True to change passwords on release of a request, otherwise false.
  • ResetPasswordOnMismatchFlag: True to queue a password change when scheduled password test fails, otherwise false.
  • ChangeFrequencyType: The change frequency for scheduled password changes:
    • first: Changes scheduled for the first day of the month.
    • last: Changes scheduled for the last day of the month.
    • xdays: Changes scheduled every x days (ChangeFrequencyDays).
  • ChangeFrequencyDays: (days: 1-999) When ChangeFrequencyType is xdays, password changes take place this configured number of days.
  • ChangeTime: (24hr format: 00:00-23:59) UTC time of day scheduled password changes take place.
• ParentAccountID: If this is a subscribed account (IsSubscribedAccount), this is the ID of the parent managed account.
• IsSubscribedAccount: True if the account is a synced or subscribed account, otherwise false.
• LastChangeDate: The date and time of the last password change.
• NextChangeDate: The date and time of the next scheduled password change.
• IsChanging: True if the account credentials are in the process of changing, otherwise false.
• ChangeState: The change state of the account credentials:
  • 0: Idle / no change taking place or scheduled within 5 minutes.
  • 1: Changing / managed account credential currently changing.
  • 2: Queued / managed account credential is queued to change or scheduled to change within 5 minutes.

Response codes

• 200 – Account was already synced. Managed Account in the response body.
• 201 – Account was synced successfully. Managed Account in the response body.

DELETE ManagedAccounts/{id}/SyncedAccounts

Purpose

Unsubscribes/unsyncs all managed accounts from the parent managed account by ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

id: ID of the parent managed account.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

DELETE ManagedAccounts/{id}/SyncedAccounts/{syncedAccountID}

Purpose

Unsubscribes/unsyncs a managed account from the managed account by ID.

Required permissions

Password Safe Account Management (Read/Write).

URL parameters

• id: ID of the parent managed account.
• syncedAccountID: ID of the synced managed account.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Deprecated

The content in this section of the guide has been deprecated and is compatible with earlier versions only.

Aliases

[deprecated] GET Aliases/{name}

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use GET Aliases?name={name} instead.

Purpose

Returns a requestable managed account alias by name.

Required roles

Requestor or Requestor/Approver role for the preferred managed account referenced by the alias.

URL parameters

name: Name of the managed account alias.

Request body

None.

Response body

Content-Type: application/json

{
    AliasId: int,
    AliasName: string,
    SystemId: int,
    SystemName: string,
    AccountId: int,
    AccountName: string,
    DomainName: string,
    InstanceName: string,
    DefaultReleaseDuration: int,
    MaximumReleaseDuration: int,
    LastChangeDate: datetime,
    NextChangeDate: datetime,
    IsChanging: bool,
    ChangeState: int,

    MappedAccounts :
    [
        {
            AliasID: int,
            ManagedSystemID: int,
            ManagedAccountID: int,
            Status: string
        },
        …
    ]
}

Response codes

200 - Request successful. Alias in response body.

Keystrokes

[deprecated] GET Keystrokes/search/{condition}

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use POST Keystrokes/Search instead.

Purpose

Search for keystrokes by condition/keyword.

Required roles

Password Safe Auditor Role, ISA Role, or a member of BeyondInsight Administrators group.

URL parameters

condition: Keyword to search for.

Response body

Content-Type: application/json

[
    {
        KeystrokeID: long, 
        SessionID: int, 
        TimeMarker: long, 
        Type: byte,
        Data: string
    },
    …
]

Response codes

200 - Request successful. Keystrokes are in response body.

[deprecated] GET Keystrokes/search/{condition}/{type:int}

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use POST Keystrokes/Search instead.

Purpose

Search for keystrokes by condition/keyword and type.

Required roles

Password Safe Auditor Role, ISA Role, or a member of BeyondInsight Administrators group.

URL parameters

• condition: Keyword to search for.
• type: Type of keystrokes:
  • 0: All
  • 1: StdIn
  • 2: StdOut
  • 4: Window Event
  • 5: User Event

Response body

Content-Type: application/json

[
    {
        KeystrokeID: long, 
        SessionID: int, 
        TimeMarker: long, 
        Type: byte,
        Data: string
    },
    …
]

Response codes

200 - Request successful. Keystrokes are in response body.

Ticket systems

GET TicketSystems

Purpose

List registered ticket systems.

Required permissions

Ticket System (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        TicketSystemID : int,
        IsActive : bool,
        TicketSystemName : string,
        Description : string,
        IsDefaultSystem : bool
    },
    …
]

Response codes

200 – Request successful. Ticket systems in the response body