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

Quick navigation

For more information on related topics, please see:

GET ManagedAccounts

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

For more information, please see the following:

Response codes

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

For more information, please see Common response codes.

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

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

For more information, please see GET ManagedAccounts.