Functional Accounts

Quick Navigation

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,
    },
    …
]

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.

Response Codes

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

For more information, please see Common Response Codes.

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,
}

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.

Response Codes

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

For more information, please see Common Response Codes.

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)

  • limit: (optional) Number of records to return (default: 1000) .
  • offset: (optional) Number of records to skip before returning <limit> records (default: 0).

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,
    },
    …
]

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,
        },
        …
    ]
}

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 allows 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-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.

POST FunctionalAccounts

Purpose

Creates a functional account.

Required Permissions

Password Safe Account Management (Read/Write).

Request Body

Content-Type: application/json

Request Body Details

  • FunctionalAccountID: (required) ID of the functional account.
  • 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 50.
  • 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) 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.

Response Body

Content-Type: application/json

{
    FunctionalAccountID: int,
    PlatformID: int,
    DomainName: string,
    AccountName: string,
    DisplayName: string,
    Password: string,
    PrivateKey : string,
    Passphrase : string,
    Description: string,
    ElevationCommand: 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.

Response Codes

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

For more information, please see Common Response Codes.

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.

For more information, please see Common Response Codes.