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 Azure Active Directory). 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.

For more information, please see Common Response Codes.