BeyondInsight and Password Safe 24.2 API Guide

BeyondInsight and Password Safe 24.2

API Guide

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC:9/4/2024

Table of Contents

BeyondInsight and Password Safe API overview 14

Usage 15

API key 15

Session state 15

Base endpoint 15

Authorization header 15

Two-Factor authentication 16

OAuth public API authentication 16

Use certificates with APIs 17

Request body 17

Common response codes 17

Authentication 22

POST Auth/SignAppin 22

POST Auth/Signout 23

OAuth public API authentication 24

POST Auth/Connect/Token 24

POST Auth/SignAppIn 25

BeyondInsight APIs 26

Access levels 27

GET AccessLevels 27

POST UserGroups/{userGroupId}/SmartRules/{smartRuleId}/AccessLevels 28

Address groups 29

GET Organizations/{orgID}/AddressGroups 29

GET AddressGroups 30

GET AddressGroups/{addressGroupId}/Addresses 31

POST AddressGroups/{id}/Addresses 32

DELETE AddressGroups/{addressGroupId} 33

DELETE AddressGroups/{addressGroupId}/Addresses 34

GET AddressGroups/?name={name} 35

GET AddressGroups/{id} 36

PUT AddressGroups/{id} 36

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

POST AddressGroups 37

GET Addresses/{id} 38

DELETE Addresses/{id} 39

PUT Addresses/{id} 40

API registrations 42

GET ApiRegistrations 42

GET ApiRegistrations/{id} 44

POST ApiRegistrations 45

PUT ApiRegistrations/{id} 48

DELETE ApiRegistrations/{id} 52

POST ApiRegistrations/{id}/Rotate 52

GET ApiRegistrations/{id}/Key 53

Assets 55

GET Assets/{id} 56

GET Workgroups/{workgroupID}/Assets 57

GET Workgroups/{workgroupName}/Assets 59

GET Workgroups/{workgroupName}/Assets?name={name} 61

POST Workgroups/{workgroupID}/Assets 62

POST Workgroups/{workgroupName}/Assets 64

PUT Assets/{id} 66

POST Assets/Search 68

DELETE Assets/{id} 70

DELETE Workgroups/{workgroupName}/Assets?name={name} 71

Smart Rule Assets 72

GET SmartRules/{id}/Assets 72

Asset attributes 74

GET Assets/{assetID}/Attributes 74

POST Assets/{assetID}/Attributes/{attributeID} 75

DELETE Assets/{assetID}/Attributes 76

DELETE Assets/{assetID}/Attributes/{attributeID} 76

Attribute types 78

GET AttributeTypes 78

GET AttributeTypes/{id} 79

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

POST AttributeTypes 79

DELETE AttributeTypes/{id} 80

Attributes 82

GET AttributeTypes/{attributeTypeID}/Attributes 82

GET Attributes/{id} 83

POST AttributeTypes/{attributeTypeID}/Attributes 84

DELETE Attributes/{id} 86

Configuration 87

GET Configuration/Version 87

Databases 88

GET Databases 88

GET Databases/{id} 89

GET Assets/{id}/Databases 90

POST Assets/{id}/Databases 91

PUT Databases/{id} 92

DELETE Databases/{id} 93

EPM Policies 95

POST /{id}/epmapplications/add 95

Entitlements 97

GET Entitlements 97

GET Entitlements?groupIDs={groupID1,groupID2,groupID3…} 98

Imports 100

POST Imports 100

Operating Systems 102

GET OperatingSystems 102

Organizations 103

GET Organizations 103

GET Organizations/{id} 104

GET Organizations?name={name} 104

Permissions 106

GET Permissions 106

User group permissions 107

GET UserGroups/{userGroupID}/Permissions 107

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

POST UserGroups/{userGroupId}/Permissions 107

DELETE UserGroups/{userGroupId}/Permissions 108

Smart Rules 110

GET SmartRules 110

GET SmartRules/{id} 111

GET UserGroups/{id}/SmartRules/ 112

GET SmartRules?title={title} 113

GET Organizations/{orgID}/SmartRules?title={title} 114

POST SmartRules/FilterAssetAttribute 115

POST SmartRules/{id}/Process 116

DELETE SmartRules/{id} 117

DELETE SmartRules?title={title} 118

DELETE Organizations/{orgID}/SmartRules?title={title} 119

Subscription delivery (Cloud only) 120

GET Subscriptions/Delivery 120

POST Subscriptions/Delivery/download?id={id} 121

User groups 123

GET UserGroups 123

GET UserGroups/{id} 124

GET UserGroups?name={name} 125

POST UserGroups 126

DELETE UserGroups/{id} 129

DELETE UserGroups?name={name} 130

User group memberships 132

GET Users/{userID}/UserGroups 132

POST Users/{userID}/UserGroups/{userGroupID} 133

DELETE Users/{userID}/UserGroups/{userGroupID} 134

User audits 135

GET UserAudits 135

GET UserAudits/{auditId:int}/UserAuditDetails 136

Users 138

GET Users 138

GET UserGroups/{userGroupId}/Users 140

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

GET Users/{id} 141

POST Users 142

POST Users/{id}/Quarantine 145

POST UserGroups/{userGroupId}/Users 146

POST/{id}/Users/{id}/RecycleClientSecret 148

PUT Users/{id} 148

DELETE Users/{id} 150

Workgroups 152

GET Workgroups 152

GET Workgroups/{id} 153

GET Workgroups?name={name} 153

POST Workgroups 154

Deprecated 156

Imports 156

Smart Rules 157

User Groups 159

Workgroups 160

Password Safe APIs 162

Access policies 163

GET AccessPolicies 163

POST AccessPolicies/Test 164

Aliases 166

GET Aliases 166

GET Aliases/{id} 167

GET Aliases?name={name} 168

Applications 171

GET Applications 171

GET Applications/{id} 172

Attributes 174

GET ManagedAccounts/{managedAccountID}/Attributes 174

GET ManagedSystems/{managedSystemID}/Attributes 175

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

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

DELETE ManagedAccounts/{managedAccountID}/Attributes 178

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

DELETE ManagedSystems/{managedSystemID}/Attributes 179

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

Credentials 182

GET Credentials/{requestId} 182

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

Custom platforms 185

GET CustomPlatforms 185

GET CustomPlatforms/{id} 186

POST CustomPlatforms/Import 187

POST CustomPlatforms/{id}/Export 188

Directories 189

GET Directories 189

GET Directories/{id} 190

POST Workgroups/{id}/Directories 191

PUT Directories/{id} 194

DELETE Directories 196

Oracle internet directories 198

GET OracleInternetDirectories 198

GET OracleInternetDirectories/{id} 199

GET Organizations/{id}/OracleInternetDirectories 199

POST OracleInternetDirectories/{id}/Services/Query 200

POST OracleInternetDirectories/{id}/Test 201

DSS key policies 203

GET DSSKeyRules 203

GET DSSKeyRules/{id} 204

Entity types 206

GET EntityTypes 206

Functional accounts 207

GET FunctionalAccounts 207

GET FunctionalAccounts/{id} 208

POST FunctionalAccounts 209

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

DELETE FunctionalAccounts/{id} 211

ISA requests 213

POST ISARequests 213

ISA sessions 215

POST ISASessions 215

Keystrokes 217

GET Sessions/{sessionId:int}/Keystrokes 217

GET Keystrokes/{id:long} 218

POST Keystrokes/Search 218

Linked accounts 220

GET ManagedSystems/{systemID}/LinkedAccounts 220

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

DELETE ManagedSystems/{systemID}/LinkedAccounts 225

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

Managed accounts 228

Role-based access 228

GET ManagedAccounts 228

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

Provisioning 233

GET ManagedAccounts/{id} 234

GET ManagedSystems/{systemID}/ManagedAccounts 237

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

PUT ManagedAccounts/{id} 243

POST ManagedSystems/{systemID}/ManagedAccounts 251

DELETE ManagedAccounts/{id} 261

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

DELETE ManagedSystems/{id}/ManagedAccounts 263

Managed account credentials 264

PUT ManagedAccounts/{managedAccountID}/Credentials 264

PUT Credentials?workgroupName={workgroupName}&assetName=

{assetName}&accountName={accountName} 265

POST ManagedAccounts/{managedAccountID}/Credentials/Test 266

POST ManagedAccounts/{managedAccountID}/Credentials/Change 267

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

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

Quick rule managed accounts 270

GET QuickRules/{quickRuleID}/ManagedAccounts 270

PUT QuickRules/{quickRuleID}/ManagedAccounts 273

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

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

Smart Rule managed accounts 280

GET SmartRules/{smartRuleID}/ManagedAccounts 280

Managed account applications 283

GET ManagedAccounts/{accountID}/Applications 283

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

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

Response codes 286

DELETE ManagedAccounts/{accountID}/Applications 286

Managed systems 287

GET ManagedSystems/{id} 288

GET ManagedSystems 291

GET Assets/{assetId}/ManagedSystems 296

GET Databases/{databaseID}/ManagedSystems 299

GET FunctionalAccounts/{id}/ManagedSystems 302

GET Workgroups/{id}/ManagedSystems 307

PUT ManagedSystems/{id} 311

POST Assets/{assetId}/ManagedSystems 319

POST Databases/{databaseID}/ManagedSystems 325

POST Workgroups/{id}/ManagedSystems 329

DELETE ManagedSystems/{id} 337

Quick rule managed systems 338

GET QuickRules/{quickRuleID}/ManagedSystems 338

PUT QuickRules/{quickRuleID}/ManagedSystems 340

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

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

Smart Rule managed systems 345

Nodes 348

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

Password policies 350

GET PasswordRules 350

GET PasswordRules?enabledproducts={productName} 351

GET PasswordRules/{id} 353

Platforms 355

GET Platforms 355

GET Platforms/{id} 356

GET EntityTypes/{id}/Platforms 358

Propagation action types 360

GET PropagationActionTypes 360

Propagation actions 361

GET PropagationActions 361

GET PropagationActions/{id} 362

Managed account propagation actions 363

GET ManagedAccounts/{id}/PropagationActions/ 363

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

DELETE ManagedAccounts/{id}/PropagationActions/ 365

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

Quick rules 367

POST QuickRules 367

GET QuickRules 369

GET QuickRules/{id} 369

GET QuickRules?title={title} 370

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

DELETE QuickRules/{id} 372

DELETE QuickRules?title={title} 373

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

Replay 375

POST pbsm/replay 375

GET pbsm/replay/{replayId} 376

PUT pbsm/replay/{replayId} 377

DELETE pbsm/replay/{replayId} 378

Requests 379

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

GET Requests 379

POST Requests 380

POST Aliases/{aliasId}/Requests 382

PUT Requests/{id}/Checkin 384

PUT Requests/{id}/Approve 385

PUT Requests/{id}/Deny 386

PUT Requests/{id}/RotateOnCheckin 387

Request termination 389

POST ManagedAccounts/{managedAccountID}/Requests/Terminate 389

POST ManagedSystems/{managedSystemID}/Requests/Terminate 390

POST Users/{userID}/Requests/Terminate 391

Request sets 392

GET RequestSets 392

POST RequestSets 393

Roles 396

GET Roles 396

User group roles 397

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

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

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

Sessions 400

GET Sessions 400

GET Sessions/{id} 402

POST Requests/{requestID}/Sessions 404

POST Sessions/Admin 406

Session locking 410

POST Sessions/{sessionID}/Lock 410

POST ManagedAccounts/{managedAccountID}/Sessions/Lock 411

POST ManagedSystems/{managedSystemID}/Sessions/Lock 411

Session termination 413

POST Sessions/{sessionID}/Terminate 413

POST ManagedAccounts/{managedAccountID}/Sessions/Terminate 414

POST ManagedSystems/{managedSystemID}/Sessions/Terminate 414

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

Synced accounts 416

GET ManagedAccounts/{id}/SyncedAccounts 416

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

DELETE ManagedAccounts/{id}/SyncedAccounts 421

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

Deprecated 424

Aliases 424

Keystrokes 425

Managed account credentials 427

Ticket systems 429

GET TicketSystems 429

Secrets Safe APIs 430

Folders 431

POST Secrets-Safe/Folders/ 431

POST Secrets-Safe/Folders/{id} 432

GET Secrets-Safe/Folders/ 433

PUT Secrets-Safe/Folders/{id} 434

DELETE Secrets-Safe/Folders/{id} 435

GET Secrets-Safe/Folders/{id} 436

Secrets 437

POST Secrets-Safe/Folders/{folderId:guid}/secrets 437

POST Secrets-Safe/Folders/{folderId:guid}/secrets/text 439

POST Secrets-Safe/Folders/{folderId:guid}/secrets/file 441

PUT Secrets-Safe/Secrets/{secretId:guid}/ 443

PUT Secrets-Safe/Secrets/{secretId:guid}/text 445

PUT Secrets-Safe/Secrets/{secretId:guid}/file 447

GET Secrets-Safe/Secrets 449

GET Secrets-Safe/Secrets/{secretId:guid} 451

GET Secrets-Safe/Folders/{folderId:guid}/secrets 452

GET Secrets-Safe/Secrets/{secretId:guid}/text 453

GET Secrets-Safe/Secrets/{secretId:guid}/file 455

GET Secrets-Safe/Secrets/{secretId:guid}/file/download 456

DELETE Secrets-Safe/Secrets/{secretId:guid}/ 457

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

Appendix 458

Migration from v1 or v2 458

Authorization header 458

Endpoint comparison 458

Endpoint mapping 459

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

This page needed for table of

contents. Do not delete.

BeyondInsight and Password Safe API overview

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.

For more information about enabling API Access, please see the following:

BeyondInsight User Guide at https://www.beyondtrust.com/docs/beyondinsight-password-safe/bi/user/index.htm

Password Safe Admin Guide at https://www.beyondtrust.com/docs/beyondinsight-password-safe/ps/admin/index.htm

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Usage

API key

The API key is a cryptographically strong random sequence of numbers hashed into a 128-character string. It is encrypted and stored

internally using AES 256 encryption. Any language with a Representational State Transfer (REST) compliant interface can access the API

with the API key and RunAs in the authorization header.

Note: Some environments may still use an old-style API key, which is a formatted Globally Unique Identifier (GUID). Rotating

the API Key produces the new-style API key described above.

Session state

Session state is maintained between API calls. The method is dependent on the scripting language. Initiate a session using API POST

Auth/SignAppIn and always call POST Auth/Signout when you are done.

Base endpoint

The following base endpoint is used throughout this document. For on-premises instances, the-server is a placeholder and should be

replaced with the server name in your environment.

<base> = https://the-server/BeyondTrust/api/public/v3

For cloud instances, the-cloud-instance-url is a placeholder and should be replaced with the cloud instance URL in your environment.

<base> = https://the-cloud-instance-url/BeyondTrust/api/public/v3

SSL is required to use the Password Safe Public API.

Authorization header

Use the web request authorization header to communicate the API application key, the RunAs username, and the user password:

key: The API key configured in BeyondInsight for your application.

runas: The username of a BeyondInsight user that has been granted permission to use the API key.

pwd: The RunAs user password surrounded by square brackets (optional; required only if the User Password is required on the

application API registration).

Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3];

Note: The API keys in the examples have been shortened for brevity. A domain user is being used. When using a domain

user, depending on the programming or scripting tool used, you may need to escape the backslash (\) character between the

domain name and username.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Two-Factor authentication

Depending on how the two-factor server is configured, a programmatic two-factor challenge is sometimes required.

No challenge

If the two-factor server is configured to authenticate through a push or mobile two-factor challenge, a challenge response is often not

required. The first call to POST Auth/SignAppIn logs the user in, as long as the authentication request to the two-factor server does not

time out.

Challenge

When a two-factor challenge is configured, two calls to POST Auth/SignAppIn are required and session state must be maintained

between these two calls to validate the two-factor challenge.

The initial call to POST Auth/SignAppIn results in a 401 Unauthorized response which contains a header WWW-Authenticate-2FA

containing the prompt from the authentication service. The prompt can be used to prompt the user for the challenge answer.

Note: If the WWW-Authenticate-2FA header is not present, a two-factor authentication challenge has not been configured for

the user.

When the challenge answer has been received from the user, POST Auth/SignAppIn is called again with the challenge answer in the

authorization header, similar to the other authorization parameters:

challenge: The answer to the two-factor challenge.

Authorization=PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe; pwd=[un1qu3];

challenge=543687;

Note: The challenge answer is only required on the second call to POST Auth/SignAppIn and not on subsequent requests.

OAuth public API authentication

The OAuth sign-in method uses the OAuth client credential flow. The client credentials grant type is used by clients to obtain an access

token outside of the context of a user.

Only users with user type Application, who are associated to an API Access Policy API registration in BeyondInsight, can use this

authentication method.

Note: Impersonation for the OAuth client credential flow is different than API key. Instead of providing the RunAs user as part

of the Authorization header you provide the RunAs user using a new RunAs header. You can only impersonate users who are

in the same group as the application user.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Note: Setting up an OAuth authentication method requires the following steps:

Create an API Registration using the API Access Policy type

Create an application user

Assign your access policy to the user

Record their client ID and secret for later use

Assign user to a group with necessary permissions

For more information, please see OAuth 2.0 Client Credentials Grant at https://oauth.net/2/grant-types/client-credentials.

Use certificates with APIs

When Client certificate required is enabled on API authentication, the following items are required to authenticate via API:

Client certificate must be present on the calling machine/instance.

Client certificate must be trusted by the appliance/Instance.

Client certificate must be included in script when calling Password Safe API.

For cloud certificate authentication, the client certificate must be signed by a well-known CA for cloud instance to trust it and allow

authentication.

Tip: The client cert can be downloaded from the Password Safe appliance/Instance in the Configuration > System >

Downloads menu.

For examples of utilizing a client cert in your API script, refer to the default scripts in the resource kit for your relevant version.

Request body

For Password Safe API Endpoints, some request bodies have multiple versions available. The request body versions allow for different

sets of data to be sent to a API endpoint dependent on what needs to be accomplished by the request. Each request body version is

outlined on its relevant endpoint and these body versions are only relevant to their listed URI.

When using a request body, if no version is specified in the URI, the default listed version is used (typically v3.0). To use a specific version,

the version must be included in the URI.

Example: https://server/BeyondTrust/api/public/v3.1/endpoint

Common response codes

Below are response codes common to all APIs. Custom responses are detailed in the individual endpoints.

200 – Request successful.

204 – Request successful. No content in body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

400 – Bad Request – Validation failure, missing request body, or string values exceed the maximum length. Reason in response

body.

401 – Unauthorized – User is not authenticated. Typical reasons include:

An invalid product license was detected.

The request headers were not set properly.

The server could not verify the validity of the request (due to one or more API factors).

The user session has expired.

The API key has been rotated but has not been updated in the calling script or application.

Tip: When you encounter a 401 error due to factor validation failure, a User Audit entry is created in BeyondInsight and an

email is sent to the administrator detailing the reason. Look here first for the reason why authorization failed.

403: – Access forbidden. User does not have the appropriate role or permission.

Tip: A 403 can also occur when SSL trust cannot be established.

404 – Object not found where expected. Reason in response body.

500 – Unexpected server error occurred. Please contact the developers.

Examples

Example: C#

Create and reuse a persistent connection using the System.Net.Http.HttpClient class.

HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("Authorization",

"PS-Auth key= c479a66f…c9484d; runas=doe-main\\johndoe;");

string json = Newtonsoft.Json.JsonConvert.SerializeObject(null);

System.Net.Http.StringContent content = new StringContent(json);

content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue

("application/json");

HttpResponseMessage signInResponse = client.PostAsync("<base>/Auth/SignAppin",

content).Result;

Subsequent calls:

HttpResponseMessage getResponse = client.GetAsync("<base>/ManagedAccounts").Result;

User Password Factor Enabled (header example only)

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("Authorization",

"PS-Auth key= c479a66f…c9484d; runas=doe-main\\johndoe; pwd=[un1qu3];");

Example: Powershell

Powershell internally creates a session variable to use for each subsequent call; Invoke-RestMethod CmdLet options -

SessionVariable and -WebSession respectively. In the below example, the variable is named "session" and has script-level

scope.

$headers = @{ Authorization="PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;"; };

$uri = "<base>/Auth/SignAppin";

$signinResult = Invoke-RestMethod -Uri $uri -Method POST -Headers $headers -

SessionVariable script:session;

Subsequent calls:

$uri = "<base>/ManagedAccounts";

$accounts = Invoke-RestMethod -Uri $uri -Method GET -WebSession $script:session -Headers

$headers;

Example: Java

Create and reuse a persistent connection using the java.net.HttpURLConnection class.

URL baseURL = new URL("HTTPS", "the-server", 443, "/BeyondTrust/api/public/v3/");

URL url = new URL(baseURL, "Auth/SignAppIn");

HttpURLConnection conn = (HttpURLConnection)url.openConnection();

conn.setRequestProperty("Authorization","PS-Auth key=c479a66f…c9484d; runas=doe-

main\\johndoe;");

Example: Ruby

Using the rest-client gem, carry over the ASP.NET_SessionId header.

samp_key = 'PS-Auth key= c479a66f…c9484d; runas=doe-main\\johndoe;'

result = RestClient::Request.execute(method: :post, url: '<base>/Auth/SignAppin',

:headers => {‘Authorization’ => samp_key} )

session_id = result.cookies["ASP.NET_SessionId"]

Subsequent calls:

result = RestClient::Request.execute(method: :get, url: '<base>/ManagedAccounts',

:headers=>{‘Authorization’ => samp_key, :cookies => {'ASP.NET_SessionId' => session_id}}

)

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Example: Python

Create and reuse a persistent connection using the requests module.

header = {'Authorization': 'PS-Auth key=c479a66f…c9484d; runas=doe-main\\johndoe;'}

session = requests.Session()

session.headers.update(header)

response = session.post('<base>/Auth/SignAppin')

Subsequent calls:

accounts = session.get('<base>/ManagedAccounts')

Example: Bash

Using curl, option –c stores authentication information for subsequent requests and –b uses it in subsequent API calls.

curl -i -c apiToken -X POST https:<base>/Auth/SignAppin -H "Content-Type:

application/json" -H "Authorization: PS-Auth key=c479a66f…c9484d; runas=doe-

main\\johndoe;" -d ""

Subsequent calls:

curl -i -b apiToken -X GET https:<base>/ManagedAccounts

Workflow

There are some loose dependencies between the APIs. A typical sequence is to list accounts or find an account, request a password,

retrieve that password (once approved), and then release the password.

Create and manage an asset, create user group, assign roles

Case: Create and manage an asset, create a managed account, create a managed account quick rule, create/provision an

LDAP/AD/BeyondInsight user group, grant Read access to new Smart Rule with requester role and access policy.

POST <base>/Auth/SignAppin

POST <base>/Workgroups/{ID}/Assets

POST <base>/Assets/{assetId}/ManagedSystems

POST <base>/ManagedSystems/{managedSystemId}/ManagedAccounts

POST <base>/QuickRules

POST <base>/UserGroups

POST <base>/UserGroups/{userGroupId}/SmartRules/{smartRuleId}/Roles

POST <base>/Auth/Signout

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Retrieve a password

Case: request, retrieve, and check in a password for a managed account:

POST <base>/Auth/SignAppin

GET <base>/ManagedAccounts OR GET <base>/ManagedAccounts?systemName={systemName}&accountName=

{accountName}

POST <base>/Requests

GET <base>/Credentials/{requestId}

PUT <base>/Requests/{requestId}/Checkin

POST <base>/Auth/Signout

Create a session

Case: request a session, create a session, and check in the request for a managed account:

POST <base>/Auth/SignAppin

GET <base>/ManagedAccounts OR GET <base>/ManagedAccounts?systemName={systemName}&accountName=

{accountName}

POST <base>/Requests (AccessType="RDP" or AccessType="SSH" or AccessType="App")

POST <base>/Requests/{requestId}/Sessions (SessionType == Request.AccessType above)

PUT <base>/Requests/{requestId}/Checkin

POST <base>/Auth/Signout

Retrieve a password as an ISA

Case: create an ISA password request:

POST <base>/Auth/SignAppin

GET <base>/ManagedAccounts OR GET <base>/ManagedAccounts?systemName={systemName}&accountName=

{accountName}

POST <base>/ISARequests

POST <base>/Auth/Signout

Create a session as an ISA

Case: create an ISA session:

POST <base>/Auth/SignAppin

GET <base>/ManagedAccounts OR GET <base>/ManagedAccounts?systemName={systemName}&accountName=

{accountName}

POST <base>/ISASessions

POST <base>/Auth/Signout

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Authentication

Quick navigation

"POST Auth/SignAppin" on page 22

"POST Auth/Signout" on page 23

"POST Auth/Connect/Token " on page 24 (OAuth)

"POST Auth/SignAppIn " on page 25 (OAuth)

POST Auth/SignAppin

Purpose

Authenticates the provided credentials and creates a user session.

Required permissions

A user group to which the user belongs must be granted access to the API key given in authorization header. Must be running script from a

valid source address as configured in API registration for the given API key.

Request body

None.

Response body

Content-Type: application/json

{

UserId: int,

SID: string,

EmailAddress: string,

UserName: string,

Name: string

}

Response codes

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

403 – Access forbidden. Returned if the Password Safe license is not valid.

410 – API version has been disabled.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

POST Auth/Signout

Purpose

Terminates the current user session.

Required permissions

None.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

OAuth public API authentication

POST Auth/Connect/Token

Purpose

Authenticates the provided credentials and allows access to the public API.

Required permissions

Application user must be associated to an API Access Policy API registration and must belong to a user group with necessary

permissions.

Request body

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=[user-client-id]&client_secret=[user-client-secret]

Response body

Content-Type: application/x-www-form-urlencoded

{

access_token: string,

expires_in: int,

token_type:string = “Bearer”,

scope: string

}

Response body details

access_token: The privileged credential to use in the Authorization header for API requests to authenticate the use.

expires_in: Lifetime (in seconds) that the token is valid.

token_type: Describes the access token (always Bearer).

scope: Describes the scope of the access token, which is what the token is allowed to perform. For application users, this consists

of only a scope called publicapi.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

POST Auth/SignAppIn

Request body

None .

Header

Authorization: Bearer [access_token]

Note: Cookies are still supported using this sign-in method.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

BeyondInsight APIs

The BeyondInsight APIs require a valid BeyondInsight license and are available to Password Safe-licensed installs.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Access levels

(i.e., None, Read, Read/Write)

Quick navigation

"GET AccessLevels" on page 27

"POST UserGroups/{userGroupId}/SmartRules/{smartRuleId}/AccessLevels" on page 28

GET AccessLevels

Purpose

Returns a list of access levels for permissions, for example, None, Read, and Read/Write.

Required permissions

User Accounts Management (Read).

Request body

None.

Response body

Content-Type: application/json

[

{

AccessLevelID:int,

Name: string,

…

]

Response codes

200 - Request successful. Access Levels in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

POST UserGroups/{userGroupId}/SmartRules/

{smartRuleId}/AccessLevels

Purpose

Sets the Access Level for a User Group Smart Rule.

Required permissions

User Accounts Management (Read/Write).

URL parameters

userGroupId: ID of the user group.

smartRuleId: ID of the Smart Rule.

Request body

Content-Type: application/json

{

AccessLevelID: int

}

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Address groups

Quick navigation

"GET Organizations/{orgID}/AddressGroups" on page 29

"GET AddressGroups" on page 30

"GET AddressGroups/{id}" on page 36

"GET AddressGroups/{addressGroupId}/Addresses" on page 31

"GET AddressGroups/?name={name}" on page 35

"POST AddressGroups/{id}/Addresses" on page 32

"POST AddressGroups" on page 37

"DELETE AddressGroups/{addressGroupId}" on page 33

"DELETE AddressGroups/{addressGroupId}/Addresses" on page 34

"PUT AddressGroups/{id}" on page 36

"GET Addresses/{id}" on page 38

"DELETE Addresses/{id}" on page 39

"PUT Addresses/{id}" on page 40

GET Organizations/{orgID}/AddressGroups

Purpose

List the address groups for a given organization.

Required permissions

Current user has access to the organization.

Asset Management (Read).

URL parameters

orgId: Organization ID.

Request body

None.

Response body

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

[

{

AddressGroupID: int,

Name: string,

OrganizationID: guid // can be null

}

]

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

GET AddressGroups

Purpose

List the address groups.

Required permissions

Current user has access to the organization.

Asset Management (Read).

URL parameters

None.

Request body

None.

Response body

Content-Type: application/json

[

{

AddressGroupID: int,

Name: string,

OrganizationID: guid // can be null

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

]

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

GET AddressGroups/{addressGroupId}/Addresses

Purpose

List the addresses for an address group.

Required permissions

Current user has access to the organization.

Asset Management (Read).

URL parameters

addressGroupId: Address Group ID.

Request body

None.

Response body

Content-Type: application/json

[

{

AddressID: int,

AddressGroupID: int,

Omit: boolean,

Type: int,

Value: string,

LastUpdatedDate: datetime

}

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body details

Type: The Address type

1: Single IP Address

2: IP Address Range

3: CIDR Notation

4: Named Host

Omit: true to omit this entry, otherwise false.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

POST AddressGroups/{id}/Addresses

Purpose

Create an address in an Address Book.

Required permissions

Asset Management (Read/Write).

URL parameters

addressGroupId: Address Group ID.

Request body

{

Type: int,

Value: string,

Omit: bool

}

Request body details

Max string length for Value is 225.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Type: The Address type

1: Single IP Address

2: IP Address Range

3: CIDR Notation

4: Named Host

Omit: true to omit this entry, otherwise false.

Response body

Content-Type: application/json

{

AddressID: int,

AddressGroupID: int,

Omit: bool,

Type: int,

Value: string,

LastUpdatedDate: datetime

}

Response body details

Type: The Address type

1: Single IP Address

2: IP Address Range

3: CIDR Notation

4: Named Host

Omit: true to omit this entry, otherwise false.

Response codes

201 - Request successful. Address in the response body.

For more information, please see "Common response codes" on page 17.

DELETE AddressGroups/{addressGroupId}

Purpose

Delete the address group and all it's addresses.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

Current user has access to the organization.

Asset Management (Read/Write).

URL parameters

addressGroupId: Address Group ID.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

DELETE AddressGroups/{addressGroupId}/Addresses

Purpose

Delete the addresses within the address group.

Required permissions

Current user has access to the organization.

Asset Management (Read/Write).

URL parameters

addressGroupId: Address Group ID.

Request body

None.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

GET AddressGroups/?name={name}

Purpose

Returns the Address Group by name.

Required permissions

Asset Management (Read).

Query parameters

Request body

None.

Response body

Content-Type: application/json

{

AddressGroupID: int,

Name: string

}

Response codes

200 - Request successful. Address Group in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET AddressGroups/{id}

Purpose

Returns the Address Group by ID.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the Address Group.

Request body

None.

Response body

Content-Type: application/json

{

AddressGroupID: int,

Name: string

}

Response codes

200 - Request successful. Address Group in the response body.

For more information, please see "Common response codes" on page 17.

PUT AddressGroups/{id}

Purpose

Updates and Address Group by ID.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

Asset Management (Read/Write).

Request body

Content-Type: application/json

{

Name: string,

}

Request body details

Max string length for Name is 225.

Response body

Content-Type: application/json

{

AddressGroupID: int,

Name: string

}

Response codes

200 - Request successful. Address Group in the response body.

For more information, please see "Common response codes" on page 17.

POST AddressGroups

Purpose

Creates an Address Book.

Required permissions

Asset Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

Content-Type: application/json

{

Name: string

}

Request body details

Max string length for Name is 225.

Response body

Content-Type: application/json

{

AddressGroupID: int,

Name: string

}

Response codes

201 - Request successful. Address Group in the response body.

For more information, please see "Common response codes" on page 17.

GET Addresses/{id}

Purpose

Returns the Address by ID.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the Address.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

Content-Type: application/json

{

AddressId: int,

AddressGroupId : int,

Omit: bool,

Type: int,

Value: string,

LastUpdateDate: datetime

}

Response body details

Type: The Address type

1: Single IP Address

2: IP Address Range

3: CIDR Notation

4: Named Host

Omit: true to omit this entry, otherwise false.

Response codes

200 - Request successful. Address in the response body.

For more information, please see "Common response codes" on page 17.

DELETE Addresses/{id}

Purpose

Deletes an Address by ID.

Required permissions

Asset Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

PUT Addresses/{id}

Purpose

Updates and Address by ID.

Required permissions

Asset Management (Read/Write).

Request body

Content-Type: application/json

{

Type: int,

Value: string,

Omit: bool

}

Request body details

Max string length for Value is 225.

Type: The Address type

1: Single IP Address

2: IP Address Range

3: CIDR Notation

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

4: Named Host

Omit: true to omit this entry, otherwise false.

Response body

Content-Type: application/json

{

AddressD: int,

AddressGroupID: int,

Omit: bool,

Type: int,

Value: string,

LastUpdateDate: datetime

}

Response body details

Type: The Address type

1: Single IP Address

2: IP Address Range

3: CIDR Notation

4: Named Host

Omit: true to omit this entry, otherwise false.

Response codes

200 - Request successful. Address in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

API registrations

Quick navigation

"GET ApiRegistrations" on page 42

"GET ApiRegistrations/{id}" on page 44

"POST ApiRegistrations" on page 45

"PUT ApiRegistrations/{id}" on page 48

"DELETE ApiRegistrations/{id}" on page 52

"POST ApiRegistrations/{id}/Rotate" on page 52

"GET ApiRegistrations/{id}/Key" on page 53

GET ApiRegistrations

Purpose

Returns a list of all API registrations.

Required permissions

API Registration Management (Read).

Query parameters

...

Request body

None.

Response body

Content-Type: application/json

{

Id: int,

Name: string,

RegistrationType: string,

Active: bool,

Visible: bool,

MultiFactorAuthenticationEnforced: bool,

ClientCertificateRequired: bool,

UserPasswordRequired: bool,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

VerifyPsrunSignature: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

CreatedDate: date

...

PSRUNRules:[

{

Id:int,

IPAddress: string,

MacAddress: string,

SystemName: string,

FQDN: string,

DomainName: string,

UserId: string,

RootVolumeId: string,

OSVersion: string,

CreatedDate: date

...

XForwardedForAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

CreatedDate: date

...

]

}

Response codes

200 – Request successful. API Registration in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET ApiRegistrations/{id}

Purpose

Returns an API registration by ID.

Required permissions

API Registration Management (Read).

Query parameters

Id: ID of the API registration.

Request body

None.

Response body

Content-Type: application/json

{

Id: int,

Name: string,

RegistrationType: string,

Active: bool,

Visible: bool,

MultiFactorAuthenticationEnforced: bool,

ClientCertificateRequired: bool,

UserPasswordRequired: bool,

VerifyPsrunSignature: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

CreatedDate: date

...

PSRUNRules:[

{

Id:int,

IPAddress: string,

MacAddress: string,

SystemName: string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

FQDN: string,

DomainName: string,

UserId: string,

RootVolumeId: string,

OSVersion: string,

CreatedDate: date

...

XForwardedForAuthenticationRules: [

{

Id: int,

Type: string,

Value: string,

Description: string,

CreatedDate: date

...

]

}

Response codes

200 – Request successful. API Registration in the response body.

For more information, please see "Common response codes" on page 17.

POST ApiRegistrations

Purpose

Creates an API registration.

Required permissions

API Registration Management (Read/Write).

Query parameters

...

Request body

The request body differs by RegistrationType.

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

ApiKeyPolicy

{

Id: int,

Name: string,

RegistrationType: string = “ApiKeyPolicy”,

Active: bool,

Visible: bool,

MultiFactorAuthenticationEnforced: bool,

ClientCertificateRequired: bool,

UserPasswordRequired: bool,

VerifyPsrunSignature: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

...

PSRUNRules:[

{

Id:int,

IPAddress: string,

MacAddress: string,

SystemName: string,

FQDN: string,

DomainName: string,

UserId: string,

RootVolumeId: string,

OSVersion: string,

...

XForwardedForAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

...

]

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

ApiAccessPolicy

{

Id: int,

Name: string,

RegistrationType: string = “ApiAccessPolicy”,

AccessTokenDuration: int = 60,

Active: bool,

Visible: bool,

ClientCertificateRequired: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

...

XForwardedForAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

...

]

}

Response body

Content-Type: application/json

{

Id: int,

Name: string,

RegistrationType: string,

AccessTokenDuration: int,

Active: bool,

Visible: bool,

MultiFactorAuthenticationEnforced: bool,

ClientCertificateRequired: bool,

UserPasswordRequired: bool,

VerifyPsrunSignature: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

CreatedDate; date

...

PSRUNRules:[

{

Id:int,

IPAddress: string,

MacAddress: string,

SystemName: string,

FQDN: string,

DomainName: string,

UserId: string,

RootVolumeId: string,

OSVersion: string,

CreatedDate; date

...

XForwardedForAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

CreatedDate; date

...

]

}

Response codes

200 – Request successful. API Registration in the response body.

For more information, please see "Common response codes" on page 17.

PUT ApiRegistrations/{id}

Purpose

Updates an API registration by ID.

Required permissions

API Registration Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Query parameters

Id: ID of the API registration.

Request body

The request body differs by Registration Type.

Content-Type: application/json

ApiKeyPolicy

{

Id: int,

Name: string,

RegistrationType: string = “ApiKeyPolicy”,

Active: bool,

Visible: bool,

MultiFactorAuthenticationEnforced: bool,

ClientCertificateRequired: bool,

UserPasswordRequired: bool,

VerifyPsrunSignature: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

...

PSRUNRules:[

{

Id:int,

IPAddress: string,

MacAddress: string,

SystemName: string,

FQDN: string,

DomainName: string,

UserId: string,

RootVolumeId: string,

OSVersion: string,

...

XForwardedForAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

...

]

}

ApiAccessPolicy

{

Id: int,

Name: string,

RegistrationType: string = “ApiAccessPolicy”,

AccessTokenDuration: int = 60,

Active: bool,

Visible: bool,

ClientCertificateRequired: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

...

XForwardedForAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

...

]

}

Response body

Content-Type: application/json

{

Id: int,

Name: string,

RegistrationType: string,

AccessTokenDuration: int,

Active: bool,

Visible: bool,

MultiFactorAuthenticationEnforced: bool,

ClientCertificateRequired: bool,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

UserPasswordRequired: bool,

VerifyPsrunSignature: bool,

IPAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

CreatedDate; date

...

PSRUNRules:[

{

Id:int,

IPAddress: string,

MacAddress: string,

SystemName: string,

FQDN: string,

DomainName: string,

UserId: string,

RootVolumeId: string,

OSVersion: string,

CreatedDate; date

...

XForwardedForAuthenticationRules:[

{

Id: int,

Type: string,

Value: string,

Description: string,

CreatedDate; date

...

]

}

Response codes

200 – Request successful. API Registration in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

DELETE ApiRegistrations/{id}

Purpose

Deletes the API Registration for the ID provided.

Required permissions

API Registration Management (Read/Write).

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

POST ApiRegistrations/{id}/Rotate

Note: For API Key Policy only.

Purpose

Rotates the API key for an API Key policy API Registration

Required permissions

API Registration Management (Read/Write).

Query parameters

...

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

Content-Type: application/json

string

Response codes

201 – Request successful. API key in the response body.

For more information, please see "Common response codes" on page 17.

GET ApiRegistrations/{id}/Key

Note: For API Key Policy only.

Purpose

Retrieves the API key for an API Key policy API Registration.

Required permissions

API Registration Management (Read/Write).

Query parameters

...

Request body

None.

Response body

Content- Type: application/json

string

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 – Request successful. API Key in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Assets

Quick navigation

"GET Assets/{id}" on page 56

"GET Workgroups/{workgroupID}/Assets" on page 57

"GET Workgroups/{workgroupName}/Assets" on page 59

"GET Workgroups/{workgroupName}/Assets?name={name}" on page 61

"POST Workgroups/{workgroupID}/Assets" on page 62

"POST Workgroups/{workgroupName}/Assets" on page 64

"PUT Assets/{id}" on page 66

"POST Assets/Search" on page 68

"DELETE Assets/{id}" on page 70

"DELETE Workgroups/{workgroupName}/Assets?name={name}" on page 71

"GET SmartRules/{id}/Assets" on page 72

For more information on related topics, please see:

"Workgroups" on page 152

"Smart Rules" on page 110

"Managed systems" on page 287

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET Assets/{id}

Purpose

Returns an asset by ID.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the asset.

Request body

None.

Response body

Content-Type: application/json

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

}

Response codes

200 - Request successful. Asset in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET Workgroups/{workgroupID}/Assets

Purpose

Returns a list of assets by Workgroup ID.

Required permissions

Asset Management (Read).

URL parameters

workgroupID: 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 <limit> records (can be used in conjunction only with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body (when limit is given)

Content-Type: application/json

{

TotalCount : int,

Data :

[

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

}

Response codes

200 - Request successful. Assets in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET Workgroups/{workgroupName}/Assets

Purpose

Returns a list of assets by Workgroup name.

Required permissions

Asset Management (Read).

URL parameters

workgroupName: Name of the Workgroup.

Query parameters (optional)

limit: (default: 100000) Number of records to return.

offset: (default: 0) Number of records to skip before returning <limit> 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,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body (when limit is given)

Content-Type: application/json

{

TotalCount : int,

Data :

[

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

}

Response codes

200 - Request successful. Assets in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET Workgroups/{workgroupName}/Assets?name={name}

Purpose

Returns an asset by Workgroup name and asset name.

Required permissions

Asset Management (Read).

URL parameters

workgroupName: Name of the Workgroup.

Query parameters

Request body

None.

Response body

Content-Type: application/json

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

}

Response codes

200 - Request successful. Asset in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

POST Workgroups/{workgroupID}/Assets

Purpose

Creates a new asset in the Workgroup, referenced by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

workgroupID: ID of the Workgroup.

Request body

Content-Type: application/json

{

IPAddress: string,

AssetName: string,

DnsName: string,

DomainName: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string

}

Request body details

IPAddress: (required) Asset IP address. Max string length is 45.

AssetName: (optional) Asset name. If not given, a padded IP address is used. Max string length is 128.

DnsName: (optional) Asset DNS name. Max string length is 255.

DomainName: (optional) Asset domain name. Max string length is 64.

MacAddress: (optional) Asset MAC address. Max string length is 128.

AssetType: (optional) Asset type. Max string length is 64.

OperatingSystem: (optional) Asset operating system. Max string length is 255.

Response body

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

}

Response codes

201 - Request successful. Asset in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

POST Workgroups/{workgroupName}/Assets

Purpose

Creates a new asset in the Workgroup referenced by name.

Required permissions

Asset Management (Read/Write).

URL parameters

workgroupName: Name of the Workgroup.

Request body

Content-Type: application/json

{

IPAddress: string,

AssetName: string,

DnsName: string,

DomainName: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string

}

Request body details

IPAddress: (required) Asset IP address. Max string length is 45.

AssetName: (optional) Asset name. If not given, a padded IP address is used. Max string length is 128.

DnsName: (optional) Asset DNS name. Max string length is 255.

DomainName: (optional) Asset domain name. Max string length is 64.

MacAddress: (optional) Asset MAC address. Max string length is 128.

AssetType: (optional) Asset type. Max string length is 64.

OperatingSystem: (optional) Asset operating system. Max string length is 255.

Response body

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

}

Response codes

201 - Request successful. Asset in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

PUT Assets/{id}

Purpose

Updates an existing asset by ID.

Tip: Call GET Assets/{id} (or equivalent) first to get the current state of the asset before calling PUT Assets/{id} to update it

with new values.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the asset.

Request body

Content-Type: application/json

{

WorkgroupID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

}

Request body details

WorkgroupID: (required) ID of the Workgroup to which the asset belongs.

AssetName: (required) Asset name.

DnsName: (required) Asset DNS name.

DomainName: (required) Asset domain name.

IPAddress: (required) Asset IP address.

MacAddress: (required) Asset MAC address. An empty value is accepted and clears any existing value.

AssetType: (required) Asset type. An empty value is accepted and clears any existing value.

OperatingSystem: (required) Asset operating system. An empty value is accepted and clears any existing value.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body

Content-Type: application/json

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

}

Response codes

200 - Request successful. Asset in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

POST Assets/Search

Purpose

Returns a list of assets that match the given search criteria.

Required permissions

Asset Management (Read).

Query parameters (optional)

limit: (default: 100000) Number of records to return.

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

Request body

Content-Type: application/json

{

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

}

Request body details

At least one request body property should be provided; any property not provided is ignored. All search criteria is case insensitive and is

an exact match (equality), except for IPAddress.

IPAddress can be a single IP address (10.0.0.1), a comma-delimited list of IPs (10.0.0.1,10.0.0.2,10.0.0.3), an IP range (10.0.0.1-

10.0.0.25), or CIDR notation (10.0.0.0/24).

Response body (when limit is not given)

Content-Type: application/json

[

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

Response body (when limit is given)

Content-Type: application/json

{

TotalCount : int,

Data :

[

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

}

Response codes

200 - Request successful. Assets in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

DELETE Assets/{id}

Purpose

Deletes an asset by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the asset.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

DELETE Workgroups/{workgroupName}/Assets?name={name}

Purpose

Deletes an asset by Workgroup name and asset name.

Required permissions

Asset Management (Read/Write).

URL parameters

workgroupName: Name of the Workgroup.

Query parameters

Request body

None.

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Smart Rule Assets

GET SmartRules/{id}/Assets

Purpose

Returns a list of assets 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 <limit> 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,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body (when limit is given)

Content-Type: application/json

{

TotalCount : int,

Data :

[

{

WorkgroupID: int,

AssetID: int,

AssetName: string,

DnsName: string,

DomainName: string,

IPAddress: string,

MacAddress: string,

AssetType: string,

OperatingSystem: string,

CreateDate: datetime,

LastUpdateDate: datetime

…

]

}

Response codes

200 - Request successful. Assets in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Asset attributes

Quick navigation

"GET Assets/{assetID}/Attributes" on page 74

"POST Assets/{assetID}/Attributes/{attributeID}" on page 75

"DELETE Assets/{assetID}/Attributes" on page 76

"DELETE Assets/{assetID}/Attributes/{attributeID}" on page 76

GET Assets/{assetID}/Attributes

Purpose

Returns a list of attributes by Asset ID.

Required permissions

Asset Management (Read), Attribute Management (Read).

URL parameters

assetID: ID of the asset.

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

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 – Request successful. Attributes associated with the asset in the response body.

For more information, please see "Common response codes" on page 17.

POST Assets/{assetID}/Attributes/{attributeID}

Purpose

Assigns an attribute to an asset.

Required permissions

Asset Management (Read/Write), Attribute Management (Read/Write).

URL parameters

assetID: ID of the asset.

attributeID: ID of the attribute Request Body.

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 in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

DELETE Assets/{assetID}/Attributes

Purpose

Deletes all asset attributes by asset ID.

Required permissions

Asset Management (Read/Write), Attribute Management (Read/Write).

URL parameters

assetID: ID of the asset.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

DELETE Assets/{assetID}/Attributes/{attributeID}

Purpose

Deletes an asset attribute by asset ID and attribute ID.

Required permissions

Asset Management (Read/Write).

Attribute Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

URL parameters

assetID: ID of the asset attributeID and ID of the attribute.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Attribute types

Quick navigation

"GET AttributeTypes" on page 78

"GET AttributeTypes/{id}" on page 79

"POST AttributeTypes" on page 79

"DELETE AttributeTypes/{id}" on page 80

GET AttributeTypes

Purpose

Returns a list of attribute types.

Required permissions

Attribute Management (Read).

Request body

None.

Response body

Content-Type: application/json

[

{

AttributeTypeID : int,

Name : string,

IsReadOnly: bool

…

]

Response codes

200 – Request successful. Attribute types in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET AttributeTypes/{id}

Purpose

Returns an attribute type by ID.

Required permissions

Attribute Management (Read).

URL parameters

id: ID of the attribute type.

Request body

None.

Response body

Content-type: application/json

{

AttributeTypeID : int,

Name : string,

IsReadOnly: bool

}

Response codes

200 – Request successful. Attribute type in the response body.

For more information, please see "Common response codes" on page 17.

POST AttributeTypes

Purpose

Creates a new attribute type.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

Attribute Management (Read/Write).

Request body

Content-Type: application/json

{

Name : string

}

Request body details

Max string length for Name is 64.

Response body

Content-type: application/json

{

AttributeTypeID : int,

Name : string,

IsReadOnly: bool

}

Response codes

201 – Request successful. Attribute type in the response body.

For more information, please see "Common response codes" on page 17.

DELETE AttributeTypes/{id}

Purpose

Deletes an attribute type and all related attributes by ID.

Required permissions

Attribute Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

URL parameters

id: ID of the attribute type.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Attributes

Quick navigation

"GET AttributeTypes/{attributeTypeID}/Attributes" on page 82

"GET Attributes/{id}" on page 83

"POST AttributeTypes/{attributeTypeID}/Attributes" on page 84

"DELETE Attributes/{id}" on page 86

GET AttributeTypes/{attributeTypeID}/Attributes

Purpose

Returns a list of attribute definitions by attribute type.

Required permissions

Attribute Management (Read).

URL parameters

attributeTypeID: ID of the attribute type.

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,

ChildAttributes :

[

{

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

AttributeID : int,

AttributeTypeID : int,

ParentAttributeID : int,

ShortName : string,

LongName : string,

Description : string,

ValueInt : int, // can be null

IsReadOnly: bool,

…

]

…

]

Response codes

200 – Request successful. Attributes in the response body.

For more information, please see "Common response codes" on page 17.

GET Attributes/{id}

Purpose

Returns an attribute definition by ID.

Required permissions

Attribute Management (Read).

URL parameters

id: ID of the attribute.

Request body

None.

Response body

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

AttributeID : int,

AttributeTypeID : int,

ParentAttributeID : int, // can be null

ShortName : string,

LongName : string,

Description : string,

ValueInt : int, // can be null

IsReadOnly: bool,

ChildAttributes :

[

{

AttributeID : int,

AttributeTypeID : int,

ParentAttributeID : int,

ShortName : string,

LongName : string,

Description : string,

ValueInt : int, // can be null

IsReadOnly: bool,

…

]

}

Response codes

200 – Request successful. Attributes in the response body.

For more information, please see "Common response codes" on page 17.

POST AttributeTypes/{attributeTypeID}/Attributes

Purpose

Creates a new attribute definition by attribute type ID.

Required permissions

Attribute Management (Read/Write).

URL parameters

attributeTypeID: ID of the attribute type.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

Content-Type: application/json

{

ParentAttributeID : int, // can be null

ShortName : string,

LongName : string,

Description : string,

ValueInt : int // can be null

}

Request body details

Max string length for ShortName and LongName is 64. Max string length for Description is 255.

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,

ChildAttributes :

[

{

AttributeID : int,

AttributeTypeID : int,

ParentAttributeID : int,

ShortName : string,

LongName : string,

Description : string,

ValueInt : int, // can be null

IsReadOnly: bool,

…

]

}

Response codes

201 – Request successful. Attributes in the response body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

DELETE Attributes/{id}

Purpose

Deletes an attribute definition by ID.

Required permissions

Attribute Management (Read/Write).

URL parameters

id: ID of the attribute.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Databases

Quick navigation

"GET Databases" on page 88

"GET Databases/{id}" on page 89

"GET Assets/{id}/Databases" on page 90

"POST Assets/{id}/Databases" on page 91

"PUT Databases/{id}" on page 92

"DELETE Databases/{id}" on page 93

For more information on related topics, please see:

"Assets" on page 55

"Platforms" on page 355

"Managed systems" on page 287

GET Databases

Purpose

Returns a list of databases.

Required permissions

Asset Management (Read).

Request body

None.

Response body

Content-Type: application/json

[

{

AssetID: int,

DatabaseID : int,

PlatformID : int,

InstanceName : string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

IsDefaultInstance : bool,

Port : int,

Version : string,

Template:string

…

]

Response codes

201 – Request successful. Databases in the response body.

For more information, please see "Common response codes" on page 17.

GET Databases/{id}

Purpose

Returns a database by ID.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the database.

Request body

None.

Response body

Content-Type: application/json

{

AssetID:int,

DatabaseID : int,

PlatformID : int,

InstanceName : string,

IsDefaultInstance : bool,

Port : int,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Version : string

}

Response codes

201 – Request successful. Databases in the response body.

For more information, please see "Common response codes" on page 17.

GET Assets/{id}/Databases

Purpose

Returns a list of databases for the given asset.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the asset.

Request body

None.

Response body

Content-Type: application/json

[

{

AssetID: int,

DatabaseID : int,

PlatformID : int,

InstanceName : string,

IsDefaultInstance : bool,

Port : int,

Version : string,

Template:string

…

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

201 – Request successful. Databases in the response body.

For more information, please see "Common response codes" on page 17.

POST Assets/{id}/Databases

Purpose

Creates a new database in the asset referenced by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the asset.

Request body

Content-Type: application/json

{

PlatformID : int,

InstanceName : string,

IsDefaultInstance : bool,

Port : int,

Version : string,

Template : string,

}

Request body details

PlatformID: (required) ID of the platform

InstanceName: Name of the database instance. Required when IsDefaultInstance is false. Max string length is 100.

IsDefaultInstance: True if the database instance is the default instance, otherwise false.

Note: Only MS SQL Server and MySQL platforms support setting this value to true.

Port: (required) The database port.

Version: The database version. Max string value is 20.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Template: The database connection template.

Response body

Content-Type: application/json

{

AssetID: int,

DatabaseID : int,

PlatformID : int,

InstanceName : string,

IsDefaultInstance : bool,

Port : int,

Version : string,

Template:string

}

Response codes

200 – Request successful. Databases in the response body.

For more information, please see "Common response codes" on page 17.

PUT Databases/{id}

Purpose

Updates an existing database by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the database.

Request body

Content-Type: application/json

{

PlatformID: int,

InstanceName: string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

IsDefaultInstance: bool,

Port: int,

Version: string,

Template: string

}

Request body details

PlatformID: (required) ID of the platform.

InstanceName: Name of the database instance. Required when IsDefaultInstance is false. Max string length is 100.

IsDefaultInstance: True if the database instance is the default instance, otherwise false.

Note: Only MS SQL Server and MySQL platforms support setting this value to true.

Port: The database port.

Version: The database version. Max string length is 20.

Template: The database connection template.

Response body

Content-Type: application/json

{

AssetID: int,

DatabaseID: int,

PlatformID: int,

InstanceName: string,

IsDefaultInstance: bool,Port: int,

Version: string,

Template: string

}

Response codes

200 – Request successful. Databases in the response body.

For more information, please see "Common response codes" on page 17.

DELETE Databases/{id}

Purpose

Deletes a database by ID.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the database.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

EPM Policies

POST /{id}/epmapplications/add

Purpose

Edits a policy to add an application, and updates this policy in the BeyondInsight database. Touches the LastModifiedDate to indicate

that a change is made. Updated policy is deployed to agents per the usual process in BeyondInsight.

Required permissions

EPM (Read/Write)

EPM Policy (Read/Write)

Query parameters (optional)

{id} is a Policy Guid

Request body

Content-Type: application/json

{

GroupName: string,

Name: string,

Path: string,

Publisher: string,

ChildrenInheritToken: boolean

}

Request body details

All fields are required.

Example request

{

"GroupName":"powershell - Add",

"Name":"notepad3.exe",

"Path":"C:\\Windows\\System32\\notepad2.exe",

"Publisher":"Microsoft2",

"ChildrenInheritToken":"false"

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body

Content-Type: application/json

{

<empty>

}

Response codes

200 – OK, successful

400 – Invalid Policy ID

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Entitlements

Quick navigation

"GET Entitlements" on page 97

"GET Entitlements?groupIDs={groupID1,groupID2,groupID3…}" on page 98

GET Entitlements

Purpose

Returns user entitlements.

Required permissions

Analytics and Reporting (Read).

URL parameters

None.

Request body

None.

Response body

Content-Type: application/json

[

{

GroupID : int,

Name : string,

SmartRuleId : int,

DistinguishedName : string,

AccessLevel : string, // can be null

RoleId : int,

RoleName : string,

DedicatedAccountPermissionOverride : string, // can be null

DedicatedToAppUserID : int, // can be null

DedicatedToAppUserName : string, // can be null

IsAdministratorGroup : bool,

UserID : int,

UserName : string,

ManagedAccountId : int,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

AccountName : string,

RationalizedSystemName : string,

ApplicationName : string,

AccessPolicyName : string

}

]

GET Entitlements?groupIDs={groupID1,groupID2,groupID3…}

Purpose

Returns user entitlements for the specified group IDs.

Required permissions

Analytics and Reporting (Read).

URL parameters

groupIDs: Comma separated list of group IDs

Request body

None.

Response body

Content-Type: application/json

[

{

GroupID : int,

Name : string,

SmartRuleId : int,

Title : string,

SmartRuleType : string,

AccessLevel : string, // can be null

RoleId : int,

RoleName : string,

DedicatedAccountPermissionOverride : string, // can be null

DedicatedToAppUserID : int, // can be null

DedicatedToAppUserName : string, // can be null

IsAdministratorGroup : bool,

UserID : int,

UserName : string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

ManagedAccountId : int,

AccountName : string,

RationalizedSystemName : string,

ApplicationName : string,

AccessPolicyName : string

}

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Imports

POST Imports

Purpose

Queues a third-party import.

Required permissions

Scan Management (Read/Write).

Request body

Content-Type: application/json

{

WorkgroupID: int,

ImportType: string,

Filter: string,

FileName: string,

FileContents: byte[],

Base64FileContents: string

}

Note: Provide either FileContents or Base64FileContents.

Request body details

WorkgroupID: ID of the Workgroup to import the assets into

ImportType: (case-senstitive, default: PASSWORDSAFE) Type of import being queued:

PASSWORDSAFE: Password Safe import file. Expected file extension: .xml.

RETINARTD: Retina© RTD file. Expected file extension: .rtd.

Note: Support for the following file types has been deprecated and will be removed from the product in a future

version.

NESSUS: Nessus© import file. Expected file extension: .csv.

NESSUSSECCEN: NessusSecurityCenter© import file. Expected file extension: .csv.

NEXPOSE: Nexpose© import file. Expected file extension: .csv or .xml.

QUALYSGUARD: QualysGuard© file. Expected file extension: .csv or .xml.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

100

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

METASPLOIT: METASPLOIT© import file. Expected file extension: .xml.

MCAFEEVM: McAfee Vulnerability Management© import file. Expected file extension: .csv.

TRIPWIRE: Tripwire© import file. Expected file extension: .csv.

Filter: (default: All Assets) Asset selection filter:

All Assets: No filter, import all.

Single IPv4 address (i.e. 10.0.0.1).

IPv4 range (i.e. 10.0.0.1-10.0.0.5).

CIDR (i.e. 10.0.0.0/24).

FileName: Filename (including extension) of the import file. One of the following is required:

FileContents: The array containing the content of the import file.

Base64FileContents: Base64 string containing the content of the import file.

Response body

Content-Type: application/json

{

ImportID: int

}

Response codes

200 – Request successful. Import ID in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

101

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Operating Systems

GET OperatingSystems

Purpose

Returns a list of operating systems.

Required permissions

Asset Management (Read).

Request body

None.

Response body

Content-Type: application/json

[

{

OperatingSystemID : int,

Name : string

…

]

Response codes

200 – Request successful. Operating systems in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

102

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Organizations

Quick navigation

"GET Organizations" on page 103

"GET Organizations/{id}" on page 104

"GET Organizations?name={name}" on page 104

GET Organizations

Purpose

Returns a list of organizations to which the current user has permission.

Required permissions

Asset Management (Read).

Request body

None.

Response body

Content-Type: application/json

[

{

OrganizationID : string,

Name : string,

IsActive : bool

…

]

Response codes

200 – Request successful. Organizations in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

103

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET Organizations/{id}

Purpose

Returns an organization by ID.

Required permissions

Current user has permission to the organization.

Asset Management (Read).

URL parameters

id: ID of the organization.

Request body

None.

Response body

Content-Type: application/json

{

OrganizationID : string,

Name : string,

IsActive : bool

}

Response codes

200 – Request successful. Organizations in the response body.

For more information, please see "Common response codes" on page 17.

GET Organizations?name={name}

Purpose

Returns an organization by name.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

104

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

Current user has permission to the organization

Asset Management (Read).

Query parameters

Request body

None.

Response body

Content-Type: application/json

{

OrganizationID : string,

Name : string,

IsActive : bool

}

Response codes

200 – Request successful. Organizations in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

105

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Permissions

(i.e., Asset Management, User Accounts Management, Scan Management, etc.)

Quick navigation

"GET Permissions" on page 106

"User group permissions" on page 107

"GET UserGroups/{userGroupID}/Permissions" on page 107

"POST UserGroups/{userGroupId}/Permissions" on page 107

"DELETE UserGroups/{userGroupId}/Permissions" on page 108

GET Permissions

Purpose

Returns a list of permissions.

Required permissions

User Accounts Management (Read).

Request body

None.

Response body

Content-Type: application/json

[

{

PermissionID : int,

Name : string

…

]

Response codes

200 – Request successful. Permissions in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

106

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

User group permissions

GET UserGroups/{userGroupID}/Permissions

Purpose

Gets all permissions for the user group referenced by ID.

Required permissions

User Accounts Management (Read).

URL parameters

userGroupId: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

[

{

PermissionID : int,

AccessLevelID : int

…]

Response codes

200 – Request successful. Permissions in the response body.

For more information, please see "Common response codes" on page 17.

POST UserGroups/{userGroupId}/Permissions

Purpose

Sets permissions for the user group referenced by ID.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

107

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

User Accounts Management (Read/Write).

Note:

Adding the Secrets Safe feature/permission to a user group requires the caller to be an administrator.

The access level for Secrets Safe cannot be changed to disabled if the group has associated secrets.

URL parameters

userGroupId: ID of the user group.

Request body

Content-Type: application/json

[

{

PermissionID : int,

AccessLevelID : int

…

]

Response body

None.

Response codes

204 – Request successful. No content in body.

For more information, please see "Common response codes" on page 17.

DELETE UserGroups/{userGroupId}/Permissions

Purpose

Deletes all permissions for the user group referenced by ID.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

108

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

User Accounts Management (Read/Write).

Note:

Removing the Secrets Safe feature/permission from a user group requires the caller to be an administrator.

Permissions for a User Group that has the Secrets Safe feature enabled cannot be deleted if the group has associated

secrets.

URL parameters

userGroupId: ID of the user group.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

109

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Smart Rules

Quick navigation

"GET SmartRules" on page 110

"GET SmartRules/{id}" on page 111

"GET UserGroups/{id}/SmartRules/" on page 112

"GET SmartRules" on page 110

"GET Organizations/{orgID}/SmartRules?title={title}" on page 114

"POST SmartRules/FilterAssetAttribute" on page 115

"POST SmartRules/{id}/Process" on page 116

"DELETE SmartRules/{id}" on page 117

"DELETE SmartRules?title={title}" on page 118

"DELETE Organizations/{orgID}/SmartRules?title={title}" on page 119

For more information on related topics, please see:

"Quick rules" on page 367

"Assets" on page 55

"GET SmartRules/{id}/Assets" on page 72

"Smart Rule managed accounts" on page 280

"GET SmartRules/{smartRuleID}/ManagedAccounts" on page 280

"GET QuickRules/{quickRuleID}/ManagedAccounts" on page 270

"Managed systems" on page 287

"Smart Rule managed systems" on page 345

GET SmartRules

Purpose

Returns a list of Smart Rules to which the current user has at least read access.

Query parameters

type: (optional, default: all) Type of Smart Rules to return (all, managed account, managed system, and asset).

Request body

None.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

110

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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. Smart Rule in the response body.

For more information, please see "Common response codes" on page 17.

GET SmartRules/{id}

Purpose

Returns a Smart Rule by ID.

Required permissions

Read access to the Smart Rule referenced by ID.

URL parameters

id: ID of the Smart Rule.

Request body

None.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

111

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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. Smart Rule in the response body.

For more information, please see "Common response codes" on page 17.

GET UserGroups/{id}/SmartRules/

Purpose

Returns a list of Smart Rules to which the given user group ID has at least read access.

Requirements

User Accounts Management (Read).

URL parameters

id: ID of the user group.

Query parameters

accessLevel: (optional, default: 1,3) User group Smart Rule access level - A single value or comma-delimited list of values:

0: None.

1: Read.

3: Read/Write.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

112

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

AccessLevelID: int,

}

,...

]

Response codes

200 – Request successful. Smart Rules with user group access level in the response body.

GET SmartRules?title={title}

Purpose

Returns a Smart Rule by title.

In a multi-tenant environment, assumes global organization.

Required permissions

Read access to the Smart Rule referenced by title.

Query parameters

title: Title of the Smart Rule.

Request body

None.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

113

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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. Smart Rule in the response body.

For more information, please see "Common response codes" on page 17.

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

Purpose

Returns a Smart Rule by organization ID and title. This is only valid in a multi-tenant environment.

Required ermissions

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

URL parameters

orgID: ID of the organization.

Query parameters

title: Title of the Smart Rule.

Request body

None.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

114

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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. Smart Rule in the response body.

For more information, please see "Common response codes" on page 17.

POST SmartRules/FilterAssetAttribute

Purpose

Specialized action for creating an asset type Smart Rule for filtering assets by attributes.

Required permissions

Asset Management (Read/Write).

Request body

Content-Type: application/json

{

AttributeIDs: [ int, …],

Title: string,

Category: string,

Description: string,

ProcessImmediately: bool

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

115

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body details

AttributeIDs: (required) A list of attribute IDs to filter by. All the attributes must be of the same attribute type.

Title: (required) The title/name of the new Smart Rule. Must be unique across all Smart Rules. Max string length is 75.

Category: (required) The category in which to place the Smart Rule. Max string length is 50.

Description: (optional, default: <value of Title>) The Smart Rule description.

ProcessImmediately: (optional, default: true) True to process the Smart Rule immediately, otherwise false to defer processing to

the background Smart Rule processor.

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

}

Response codes

201 - Request successful. Smart Rule in response body.

For more information, please see "Common response codes" on page 17.

POST SmartRules/{id}/Process

Purpose

Process a Smart Rule by ID.

Required permissions

Read/Write access to the Smart Rule.

URL parameters

ID: ID of the Smart Rule.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

116

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Query parameters

Queue: (default: false) True to queue the Smart Rule for processing; false to process the Smart Rule immediately.

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. Smart Rule in the response body.

409 – Conflict: the Smart Rule is currently processing.

For more information, please see "Common response codes" on page 17.

DELETE SmartRules/{id}

Purpose

Deletes a Smart Rule by ID.

Required permissions

Read/Write access to the Smart Rule referenced by ID

URL parameters

ID: ID of the Smart Rule.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

117

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

DELETE SmartRules?title={title}

Purpose

Deletes a Smart Rule by title.

In a multi-tenant environment, assumes global organization.

Required permissions

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

Query parameters

title: Title of the Smart Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

118

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

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

Purpose

Deletes a Smart Rule by organization ID and title.

Only valid in a multi-tenant environment.

Required permissions

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

URL parameters

orgID: ID of the organization.

Query parameters

title: Title of the Smart Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

119

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Subscription delivery (Cloud only)

Quick navigation

"GET Subscriptions/Delivery" on page 120

"POST Subscriptions/Delivery/download?id={id}" on page 121

GET Subscriptions/Delivery

Purpose

Returns a list of IDs for all subscription deliveries that a user has access to. Administrators have access to all deliveries while other users

only have access to deliveries they created.

Required permissions

Analytics and Reporting (Read).

URL parameters

None.

Request body

None.

Response body

Content-Type: application/json

[

{

int[]

}

]

Response body details

A list of ints that reference the ReportDeliveryId field for every subscription delivery that the user has access to.

Response codes

200 – Request successful. Ids in the response body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

120

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

POST Subscriptions/Delivery/download?id={id}

Purpose

Returns the subscription delivery for the requested id.

Required permissions

Analytics and Reporting (Read).

URL parameters

id: ID of the request for which to retrieve the subscription delivery.

Request body

None.

Response body

Content-Type: application/json

[

{

ReportDeliveryId : int,

ScheduleId : int,

Filename : string,

ApplicationType : string,

Snapshot : string,

}

]

Response body details

ReportDeliveryId: The ID of this subscription delivery in the database.

ScheduleId: Schedule ID of the subscription associated with this subscription delivery.

ApplicationType: The MIME type string identifying the format of the file. Will be one of the following:

application/msword (Word)

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (Excel)

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

121

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

application/pdf (Pdf)

image/tiff (TIFF)

text/csv (CSV)

Snapshot: A Base64 string representing the byte array of the subscription delivery file itself.

Response codes

200 – Request successful. Subscription delivery in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

122

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

User groups

Quick navigation

"GET UserGroups" on page 123

"GET UserGroups/{id}" on page 124

"GET UserGroups?name={name}" on page 125

"POST UserGroups" on page 126

"DELETE UserGroups/{id}" on page 129

"DELETE UserGroups?name={name}" on page 130

GET UserGroups

Purpose

Returns a list of active and inactive user groups.

Required permissions

User Accounts Management (Read).

Request body

None.

Response body

Content-Type: application/json

[

{

GroupID : int,

Name : string,

DistinguishedName : string,

Description : string,

GroupType : string,

AccountAttribute : string,

ApplicationRegistrationIDs : string,

MembershipAttribute : string,

IsActive : bool

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

123

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 – Request successful. User group in the response body.

For more information, please see "Common response codes" on page 17.

GET UserGroups/{id}

Purpose

Returns a user group by ID.

Required permissions

User Accounts Management (Read).

URL parameters

id: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

[

{

GroupID : int,

Name : string,

DistinguishedName : string,

Description : string,

GroupType : string,

AccountAttribute : string,

ApplicationRegistrationIDs : string,

MembershipAttribute : string,

IsActive : bool

}

]

Response codes

200 – Request successful. User group in the response body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

124

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

GET UserGroups?name={name}

Purpose

Returns a user group by name.

Required permissions

User Accounts Management (Read).

Query parameters

Request body

None.

Response body

Content-Type: application/json

[

{

GroupID : int,

Name : string,

DistinguishedName : string,

GroupType : string,

AccountAttribute : string,

ApplicationRegistrationIDs : string,

MembershipAttribute : string,

IsActive : bool

}

]

Response codes

200 – Request successful. User group in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

125

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

POST UserGroups

Purpose

Creates a new user group with permissions, and, optionally, Smart Rule access and application registration IDs.

Required permissions

User Accounts Management (Read/Write).

Note: Creating a user group that has the Secrets Safe feature/permission enabled requires the caller to be an administrator.

Request body

The request body differs for the different group types available: BeyondInsight, ActiveDirectory, LdapDirectory.

BeyondInsight group type

Request body

Content-Type: application/json

{

groupType : string = "BeyondInsight",

groupName : string,

description : string,

isActive : bool,

Permissions : [ { PermissionID: int, AccessLevelID: int }, ... ],

SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ],

ApplicationRegistrationIDs: [ int, … ]

}

Request body details

groupName: (required) Name of the BeyondInsight user group. Max string length is 200.

description: (required) Description of the user group. Max string length is 255.

For more information, please see "Common request body details" on page 128.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

126

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

ActiveDirectory group type

Request body

Content-Type: application/json

{

groupType : string = "ActiveDirectory",

groupName : string,

forestName : string,

domainName : string,

description : string,

bindUser : string,

bindPassword : string,

useSSL : bool,

isActive : bool,

ExcludedFromGlobalSync : bool,

OverrideGlobalSyncSettings : bool,

Permissions : [ { PermissionID: int,

AccessLevelID: int }, ... ],

SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ],

ApplicationRegistrationIDs: [ int, … ]

}

Request body details

groupName: (required) Name of the Active Directory group. Max string length is 200.

domainName: (required) The directory domain name. Max string length is 250.

description: (required) Description of the user group. Max string length is 255.

bindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory. If specifying an

existing credential, you also need Credential Management – Read. If specifying a new credential, you also need Credential

Management – Read/Write.

bindPassword: Password for directory binding (required if bindUser is given).

forestName: The directory forest name (required when bindUser is given). Max string length is 300.

useSSL: (default: false) Flag indicating whether to use SSL.

ExcludedFromGlobalSync: (default false) Flag indicating if the Active Directory group uses the global group synchronization

settings.

OverrideGlobalSyncSettings: (default false) Flag indicating if the Active Directory group overrides the global group

synchronization settings.

For more information, please see "Common request body details" on page 128.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

127

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

LdapDirectory group type

Request body

Content-Type: application/json

{

groupType : string = "LdapDirectory",

groupName : string,

groupDistinguishedName : string,

hostName : string,

bindUser : string,

bindPassword : string,

port : int,

useSSL : bool,

membershipAttribute : string,

accountAttribute : string,

isActive : bool,

Permissions : [ { PermissionID: int,

AccessLevelID: int }, ... ],

SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ],

ApplicationRegistrationIDs: [ int, … ]

}

Request body details

groupName: (required) Name of the LDAP group. Max string length is 200.

groupDistinguishedName: (required) Distinguished name of the LDAP group. Max string length is 500.

hostName: (required) The directory server host name or IP. Max string length is 50.

bindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory. If specifying an

existing credential, you also need Credential Management – Read. If specifying a new credential, you also need Credential

Management – Read/Write.

bindPassword: Password for directory binding (Note: required if bindUser is given).

port: Directory server port (valid range: 1 to 65535) (required if bindUser is given).

useSSL: (default: false) Flag indicating whether to use SSL (required if bindUser is given).

membershipAttribute: (required) Directory group membership attribute. Max string length is 255.

accountAttribute: (required) Directory account naming attribute. Max string length is 255.

For more information, please see "Common request body details" on page 128.

Common request body details

isActive: (default: true) True if the group should be created as active, otherwise false.

Permissions: One or more permissions and access levels to set for the new user group.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

128

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

SmartRuleAccess: One or more Smart Rules and access levels to set for the new user group.

ApplicationRegistrationIDs: Zero or more IDs representing the API application registrations to grant the new user group. If

given, enables API for the user group.

Response body

Content-Type: application/json

[

{

GroupID : int, Name : string,

DistinguishedName : string,

Description : string,

GroupType : string,

AccountAttribute : string,

MembershipAttribute : string,

IsActive : bool

}

]

Response codes

201 – Request successful. User group in the response body.

For more information, please see "Common response codes" on page 17.

DELETE UserGroups/{id}

Purpose

Deletes a user group by ID.

Required permissions

User Accounts Management (Read/Write).

Note:

Deleting a user group that has the Secrets Safe feature/permission enabled requires the caller to be an administrator.

User Groups that have the Secrets Safe feature enabled cannot be deleted if the group has associated secrets.

URL parameters

id: ID of the user group.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

129

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

DELETE UserGroups?name={name}

Purpose

Deletes a user group by name.

Required permissions

User Accounts Management (Read/Write).

Note: Deleting a user group that has the Secrets Safe feature/permission enabled requires the caller to be an administrator.

Query parameters

Request body

None.

Response body

None.

Response codes

200 – Request successful.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

130

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

131

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

User group memberships

Quick navigation

"GET Users/{userID}/UserGroups" on page 132

"POST Users/{userID}/UserGroups/{userGroupID}" on page 133

"DELETE Users/{userID}/UserGroups/{userGroupID}" on page 134

GET Users/{userID}/UserGroups

Purpose

Returns the user group memberships for an existing user.

Required permissions

User Accounts Management (Read).

URL parameters

userID: ID of the user.

Request body

None.

Response body

Content-Type: application/json

[

{

GroupID : int,

Name : string,

DistinguishedName : string,

GroupType : string,

AccountAttribute : string,

MembershipAttribute : string,

IsActive : bool

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

132

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 – Request successful. User group in the response body.

For more information, please see "Common response codes" on page 17.

POST Users/{userID}/UserGroups/{userGroupID}

Purpose

Adds an existing user to a user group.

Required permissions

User Accounts Management (Read/Write).

URL parameters

userID: ID of the user.

userGroupID: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

{

GroupID : int, Name : string,

DistinguishedName : string,

GroupType : string,

AccountAttribute : string,

MembershipAttribute : string,

IsActive : bool

}

Response codes

201 – Request successful. User group in the response body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

133

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

DELETE Users/{userID}/UserGroups/{userGroupID}

Purpose

Removes a user from a user group.

Required permissions

User Accounts Management (Read/Write).

URL parameters

userID: ID of the user.

userGroupID: ID of the user group.

Request body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

134

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

User audits

GET UserAudits

Purpose

Returns a list of user audits.

Required permissions

User Audit Management (Read).

Query parameters (optional)

username: User name.

actiontype: Action type.

section: Section.

startdate: Start date.

enddate: End date.

limit: (default: 1000) Number of records to return.

offset: (default: 0) Number of records to skip before returning records.

Request body

None.

Response body

Content-Type: application/json

{

TotalCount : int,

Data: [

{

AuditID : int,

ActionType : string,

Section : string,

UserID : int,

UserName : string,

IPAddress : string,

CreateDate : datetime

...

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

135

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

]

}

Response codes

200 – Request successful. User Audits in response body.

Default sort

By default the records are sorted by CreateDate in descending order (latest entries are shown first)

GET UserAudits/{auditId:int}/UserAuditDetails

Purpose

Returns a list of user audit details.

Required permissions

User Audit Management (Read).

Query parameters

auditid: Audit ID

limit: (default: 1000) Number of records to return.

offset: (default: 0) Number of records to skip before returning records.

Request body

None.

Response body

Content-Type: application/json

{

TotalCount: int,

Data: [

{

AuditDetailsID : int,

Name: string,

OldValue : string,

NewValue : string

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

136

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

...

]

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

137

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Users

Quick navigation

"GET Users" on page 138

"GET UserGroups/{userGroupId}/Users" on page 140

"GET Users/{id}" on page 141

"POST Users" on page 142

"POST Users/{id}/Quarantine" on page 145

"POST UserGroups/{userGroupId}/Users" on page 146

"PUT Users/{id}" on page 148

"DELETE Users/{id}" on page 150

"POST/{id}/Users/{id}/RecycleClientSecret" on page 148

GET Users

Purpose

Returns a list of all users if username parameter is not supplied. Otherwise returns the requested user.

Note: Some usernames may be in the format hostname\username, if not represented by an email address.

Required permissions

User Accounts Management (Read).

Query parameters (optional)

username: The user to return, in one of following formats:

username: returns the BeyondInsight users.

domain\username or universal principal name: returns Active Directory or LDAP users.

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

Note: A username search without a domain finds local users; if domain is added to the search, it finds the user for a given

domain.

Note: Use of the optional query parameters results in the supplied value being recorded in the web server log file.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

138

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

Content-Type: application/json

[

{

UserID : int,

UserName : string,

DomainName : string,

DistinguishedName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

LastLoginDate : DateTime,

LastLoginAuthenticationType : string,

LastLoginConfigurationName : string,

LastLoginSAMLIDPURL : string,

LastLoginSSOURL : string,

IsQuarantined: bool,

IsActive : bool

…

]

Application user type:

Note: ClientSecret has no value; it can only be retrieved via API by initial creation or recycling it. Please see "Users" on page

138.

{

ClientID: string,

ClientSecret: string = null,

AccessPolicyID: int,

UserID: int,

UserType: string = "Application",

UserName: string,

DomainName: string = null,

DistinguishedName: string = null,

FirstName: string = null,

LastName: string = null,

EmailAddress: string = null,

IsQuarantined: bool,

IsActive : bool

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

139

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 – Request successful. Users in the response body.

For more information, please see "Common response codes" on page 17.

GET UserGroups/{userGroupId}/Users

Purpose

Returns a list of users for the user group referenced by ID.

Note: For Active Directory, Entra ID, or LDAP user groups, calling this endpoint also triggers the membership synchronization

between the directory and BeyondInsight for the group identified by userGroupId.

Required permissions

User Accounts Management (Read).

URL parameters

userGroupId: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

[

{

UserID : int,

UserName : string,

DomainName : string,

DistinguishedName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

LastLoginDate : DateTime,

LastLoginAuthenticationType : string,

LastLoginConfigurationName : string,

LastLoginSAMLIDPURL : string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

140

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

LastLoginSSOURL : string,

IsQuarantined: bool,

IsActive : bool

…

]

Response codes

200 – Request successful. Users in the response body.

For more information, please see "Common response codes" on page 17.

GET Users/{id}

Purpose

Returns a user by ID.

Required permissions

User Accounts Management (Read).

URL parameters

id: ID of the user.

Request body

None.

Response body

Content-Type: application/json

[

{

UserID : int,

UserName : string,

DomainName : string,

DistinguishedName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

141

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

LastLoginDate : DateTime,

LastLoginAuthenticationType : string,

LastLoginConfigurationName : string,

LastLoginSAMLIDPURL : string,

LastLoginSSOURL : string,

IsQuarantined: bool,

IsActive : bool

}

]

Application user type

Note: ClientSecret has no value; it can only be retrieved via API by initial creation or recycling it. Please see "Users" on page

138.

{

ClientID: string,

ClientSecret: string = null,

AccessPolicyID: int,

UserID: int,

UserType: string = "Application",

UserName: string,

DomainName: string = null,

DistinguishedName: string = null,

FirstName: string = null,

LastName: string = null,

EmailAddress: string = null,

IsQuarantined: bool,

IsActive : bool

}

Response codes

200 – Request successful. User in the response body.

For more information, please see "Common response codes" on page 17.

POST Users

Purpose

Creates a new user with no user group associations.

Required permissions

User Accounts Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

142

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

The request body differs for the different user types available: BeyondInsight, ActiveDirectory, LdapDirectory

BeyondInsight user type

Content-Type: application/json

{

UserType : string = "BeyondInsight",

UserName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

Password : string

}

Request body details

UserName: (required) Username of the user account. Max string length is 64.

FirstName: (required) First name of the user. Max string length is 64.

LastName: (optional) Last name of the user. Max string length is 64.

EmailAddress: (required must be a properly formatted address) - Email address for the user. Max string length is 255.

Password: (required) The password they would use to login to BeyondInsight.

ActiveDirectory user type

Content-Type: application/json

{

UserType : string = "ActiveDirectory",

UserName : string,

ForestName : string,

DomainName : string,

BindUser : string,

BindPassword : string,

UseSSL : bool,

}

Request body details

UserName: (required) Name of the Active Directory user. Max string length is 64.

DomainName: (required) The directory domain name. Max string length is 250.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

143

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

BindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory.

BindPassword: Password for directory binding (required when BindUser is given).

ForestName: The directory forest name (required when BindUser is given). Max string length is 300.

UseSSL: (default: false) Flag indicating whether to use SSL.

LdapDirectory user type

Content-Type: application/json

{

UserType: string = "LdapDirectory",

HostName: string,

DistinguishedName: string,

AccountNameAttribute: string,

BindUser: string,

BindPassword: string,

Port: int,

UseSSL: bool

}

Request body details

HostName: (required) The directory server host name or IP.

DistinguishedName: (required) The DistinguishedName of the user to create. Max string length is 255.

AccountNameAttribute: (required) The LDAP attribute to use for creating the username.

BindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory.

BindPassword: Password for directory binding. (required if BindUser is given).

Port: The directory server port. (used when BindUser and BindPassword are given).

UseSSL: Flag indicating whether to use SSL (used when BindUser and BindPassword are given).

Application user type

{

UserType: string = "Application",

UserName: string,

AccessPolicyID: int

}

For more information, please see "Common request body details" on page 128.

Response body

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

144

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

[

{

UserID : int,

UserName : string,

DomainName : string,

DistinguishedName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

IsQuarantined: bool,

IsActive : bool

}

]

Application user type

{

ClientID: string,

ClientSecret: string,

AccessPolicyID: int,

UserID: int,

UserType: string = "Application",

UserName: string,

DomainName: string = null,

DistinguishedName: string = null,

FirstName: string = null,

LastName: string = null,

EmailAddress: string = null,

IsQuarantined: bool,

IsActive : bool

}

Response codes

200 – Request successful. User in the response body.

For more information, please see "Common response codes" on page 17.

POST Users/{id}/Quarantine

Purpose

Quarantines the user referenced by ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

145

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

URL parameters

id: ID of the BeyondInsight user.

Request body

None.

Response body

Content- Type: application/json

[

{

UserID : int,

UserName : string,

DomainName : string,

DistinguishedName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

IsQuarantined: bool,

IsActive : bool

}

]

Response codes

200 – Request successful. User in the response body.

For more information, please see "Common response codes" on page 17.

POST UserGroups/{userGroupId}/Users

Purpose

Creates a user in a BeyondInsight-type user group.

Required permissions

User Accounts Management (Read/Write).

URL parameters

userGroupId: ID of the user group.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

146

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

Content-Type: application/json

{

UserName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

Password : string

}

Request body details

UserName: (required) Username of the user account. Max string length is 64.

FirstName: (required) First name of the user. Max string length is 64.

LastName: (optional) Last name of the user. Max string length is 64.

EmailAddress: (required and must be a properly formatted address) Email address for the user. Max string length is 255.

Password: (required) The password they would use to login to BeyondInsight.

Response body

Content-Type: application/json

[

{

UserID : int,

UserName : string,

DomainName : string,

DistinguishedName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

IsQuarantined: bool,

IsActive : bool

}

]

Response codes

201 – Request successful. User in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

147

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

POST/{id}/Users/{id}/RecycleClientSecret

Note: For application user type only.

Purpose

Recycles the client secret for an application user.

Required permissions

User Accounts Management (Read/Write) or logged in as the user being affected.

Request body

None.

Response body

Content- Type: application/json

string

Response codes

200 – Request successful. New client secret in the body.

For more information, please see "Common response codes" on page 17.

PUT Users/{id}

Purpose

Updates a BeyondInsight user by ID.

Note: Cannot update ActiveDirectory or LDAP users.

Required permissions

User Accounts Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

148

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

URL parameters

id: ID of the BeyondInsight user.

Request body

Content-Type application/json

{

UserName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

Password: string

}

Request body details

UserName: (required) Username of the user account.

FirstName: (required) First name of the user.

LastName: (optional) Last name of the user.

EmailAddress: (required and must be a properly formatted address) Email address for the user.

Password: (optional) The password they would use to log in to BeyondInsight. If given, replaces the current password.

Application user type

{

UserName: string,

AccessPolicyID: int

}

Response body

Content- Type: application/json

[

{

UserID : int,

UserName : string,

DomainName : string,

DistinguishedName : string,

FirstName : string,

LastName : string,

EmailAddress : string,

IsQuarantined: bool,

IsActive : bool

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

149

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

}

]

Application user type

Note: ClientSecret has no value; it can only be retrieved via API by initial creation or recycling it. Please see "Users" on page

138.

{

ClientID: string,

ClientSecret: string = null,

AccessPolicyID: int,

UserID: int,

UserType: string = "Application",

UserName: string,

DomainName: string = null,

DistinguishedName: string = null,

FirstName: string = null,

LastName: string = null,

EmailAddress: string = null,

IsQuarantined: bool,

IsActive : bool

}

Response codes

200 – Request successful. User in the response body.

For more information, please see "Common response codes" on page 17.

DELETE Users/{id}

Purpose

Deletes a user by ID.

Required permissions

User Accounts Management (Read/Write).

Note:

Users that have the Secrets Safe feature enabled cannot be deleted if that user is the only owner of at least one

secret.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

150

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

If the user is not the sole owner of any secrets, but is one of multiple owners of a secret, then no error will be presented

and the user can be deleted successfully. They will also be removed from the secrets they are part owners to.

URL parameters

id: ID of the user.

Request body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

151

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Workgroups

Quick navigation

"GET Workgroups" on page 152

"GET Workgroups/{id}" on page 153

"GET Workgroups?name={name}" on page 153

"POST Workgroups" on page 154

GET Workgroups

Purpose

Returns a list of Workgroups to which the current user has permission.

Request body

None.

Response body

Content-Type: application/json

[

{

OrganizationID : string, ID : int,

Name : string

…

]

Response codes

200 – Request successful. Workgroups in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

152

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

GET Workgroups/{id}

Purpose

Returns a Workgroup by ID.

Required permissions

Current user has permission to the Workgroup Organization.

Asset Management (Read) or Scan Management (Read/Write).

Query parameters

id: ID of the Workgroup.

Request body

None.

Response body

Content-Type: application/json

{

OrganizationID : string,

ID : int,

Name : string

}

Response codes

200 – Request successful. Workgroups in the response body.

For more information, please see "Common response codes" on page 17.

GET Workgroups?name={name}

Purpose

Returns a Workgroup by name.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

153

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

Current user has permission to the Workgroup Organization. Asset Management (Read) or Scan Management (Read/Write).

Query parameters

Request body

None.

Response body

Content-Type: application/json

{

OrganizationID : string,

ID : int,

Name : string

}

Response codes

200 – Request successful. Workgroups in the response body.

For more information, please see "Common response codes" on page 17.

POST Workgroups

Purpose

Creates a Workgroup.

Required permissions

Asset Management (Read/Write).

Request body

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

154

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

OrganizationID: string,

Name : string

}

Request body details

Organization ID: (optional) The ID of the organization in which to place the new Workgroup. If empty, the Workgroup is placed in

the default organization.

Name: The name of the Workgroup. Max string length is 256.

Response body

Content-Type: application/json

{

OrganizationID : string,

ID : int,

Name : string

}

Response codes

201 – Request successful. Workgroups in the response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

155

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Deprecated

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

Quick navigation

"[deprecated] POST Imports/QueueImportFile" on page 156

"[deprecated] POST SmartRules/FilterSingleAccount" on page 157

"[deprecated] GET UserGroups/{name}" on page 159

"[deprecated] DELETE UserGroups/{name}" on page 160

"[deprecated] GET Workgroups/{name}" on page 160

Imports

[deprecated] POST Imports/QueueImportFile

Note: This API has been deprecated and is available for backwards compatibility only. Use POST Imports with

Base64FileContents instead.

Purpose

Queues a Password Safe XML import using multi-part form-data content.

Required permissions

Scan Management (Read/Write).

Request body

Content-Type: multipart/form-data

{

Content-type: application/json

{

WorkgroupID: int,

FileName: string

}

application/octet-stream

{

<string-encoded byte array representing the file>

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

156

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body details

WorkgroupID: ID of the Workgroup to import the assets into.

FileName: Filename (including extension) of the import file.

Response body

Content-Type: application/json

{

ImportID: int

}

Response codes

200 – Request successful. Import ID in the response body.

400 – The import file was not found in the body of the request, or a request body validation error has occurred.

Smart Rules

[deprecated] POST SmartRules/FilterSingleAccount

Note: This API has been deprecated and is available for backwards compatibility only. Use QuickRules instead.

Purpose

Specialized action for creating a Managed Account-type Smart Rule for filtering a single Managed Account by System Name and Account

Name.

Required permissions

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

Request body

Content-type: application/json

{

AccountID: int,

Title: string

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

157

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body details

AccountID: (required) ID of the managed account you want to filter by parent System Name and Account Name.

Title: (optional) The title/name of the new Smart Rule. If omitted, a unique title is auto-generated.

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. Smart Rule in the response body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

158

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

User Groups

[deprecated] GET UserGroups/{name}

Note: This API has been deprecated and is available for backwards compatibility only. Use GET UserGroups?name=

{name} instead.

Purpose

Returns a user group by name.

Required permissions

User Accounts Management (Read).

URL parameters

Request body

None.

Response body

Content-Type: application/json

{

GroupID : int, Name : string,

DistinguishedName : string,

GroupType : string,

AccountAttribute : string,

MembershipAttribute : string,

IsActive : bool

}

Response codes

200 – Request successful. User group in the response body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

159

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

[deprecated] DELETE UserGroups/{name}

Note: This API has been deprecated and is available for backwards compatibility only. Use DELETE UserGroups?name=

{name} instead.

Purpose

Deletes a user group by name.

Required permissions

User Accounts Management (Read/Write).

URL parameters

Request body

None.

Response body

None.

Response Codes

200 – Request successful.

Workgroups

[deprecated] GET Workgroups/{name}

Note: This API has been deprecated and is available for backwards compatibility only. Use GET Workgroups?name=

{name} instead.

Purpose

Returns a Workgroup by name.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

160

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required permissions

Current user has permission to the Workgroup Organization. Asset Management (Read) or Scan Management (Read/Write).

Query parameters

Request body

None.

Response body

Content-Type: application/json

{

OrganizationID : string,

ID : int,

Name : string

}

Response codes

200 – Request successful. Workgroups in the response body.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

161

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Password Safe APIs

Password Safe APIs require a valid Password Safe license.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

162

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Access policies

Quick navigation

"GET AccessPolicies" on page 163

"POST AccessPolicies/Test" on page 164

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

163

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

…

]

…

]

…

]

Response codes

200 - Request successful. Access policies in response body.

For more information, please see "Common response codes" on page 17.

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

164

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

165

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Aliases

Quick navigation

"GET Aliases" on page 166

"GET Aliases/{id}" on page 167

"GET Aliases?name={name}" on page 168

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

166

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

167

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

GET Aliases?name={name}

Purpose

Returns a requestable managed account alias by name.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

168

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Required roles

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

URL parameters

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

169

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

170

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Applications

Quick navigation

"GET Applications" on page 171

"GET Applications/{id}" on page 172

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

}

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

171

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 - Request successful. Applications in response body.

For more information, please see "Common response codes" on page 17.

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

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

172

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 - Request successful. Application in response body.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

173

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Attributes

Quick navigation

"GET ManagedAccounts/{managedAccountID}/Attributes" on page 174

"GET ManagedSystems/{managedSystemID}/Attributes" on page 175

"POST ManagedAccounts/{managedAccountID}/Attributes/{attributeID}" on page 176

"POST ManagedSystems/{managedSystemID}/Attributes/{attributeID}" on page 177

"DELETE ManagedAccounts/{managedAccountID}/Attributes" on page 178

"DELETE ManagedAccounts/{managedAccountID}/Attributes/{attributeID}" on page 179

"DELETE ManagedSystems/{managedSystemID}/Attributes" on page 179

"DELETE ManagedSystems/{managedSystemID}/Attributes/{attributeID}" on page 180

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

174

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Description : string, ValueInt : int, // can be null

IsReadOnly: bool

…

]

Response codes

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

For more information, please see "Common response codes" on page 17.

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

175

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

…

]

Response codes

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

For more information, please see "Common response codes" on page 17.

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

176

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

…

]

Response codes

201 - Request successful. Attribute in the response body.

For more information, please see "Common response codes" on page 17.

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

177

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

…

]

Response codes

201 - Request successful. Attribute in the response body.

For more information, please see "Common response codes" on page 17.

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

178

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

179

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

URL parameters

managedSystemID: ID of the managed system.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

180

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

181

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Credentials

Quick navigation

"GET Credentials/{requestId}" on page 182

"GET Aliases/{aliasId}/Credentials/{requestId}" on page 183

For more information on related topics, please see:

"Requests" on page 379

"Aliases" on page 166

"Managed accounts" on page 228

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

182

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

183

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

184

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

Quick navigation

"GET CustomPlatforms" on page 185

"GET CustomPlatforms/{id}" on page 186

"POST CustomPlatforms/Import" on page 187

"POST CustomPlatforms/{id}/Export" on page 188

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

185

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

186

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

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,

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

187

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response body details

PlatformId: The ID of the custom platform.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

188

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Directories

Quick navigation

"GET Directories" on page 189

"GET Directories/{id}" on page 190

"POST Workgroups/{id}/Directories" on page 191

"PUT Directories/{id}" on page 194

"DELETE Directories" on page 196

For more information on related topics, please see "Managed systems" on page 287.

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

189

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

190

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

191

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

192

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

193

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

194

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

195

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

196

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

None.

Response codes

200 – Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

197

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Oracle internet directories

Quick navigation

"GET OracleInternetDirectories" on page 198

"GET OracleInternetDirectories/{id}" on page 199

"GET Organizations/{id}/OracleInternetDirectories" on page 199

"POST OracleInternetDirectories/{id}/Services/Query" on page 200

"POST OracleInternetDirectories/{id}/Test" on page 201

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

198

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

GET Organizations/{id}/OracleInternetDirectories

Purpose

Returns a list of Oracle Internet Directories by organization ID.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

199

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

200

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

201

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

Success : bool,

}

Response codes

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

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

202

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

Quick navigation

"GET DSSKeyRules" on page 203

"GET DSSKeyRules/{id}" on page 204

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

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

203

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

204

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

205

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Entity types

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

For more information on related topics, please see "Platforms" on page 355.

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

206

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Functional accounts

Quick navigation

"GET FunctionalAccounts" on page 207

"GET FunctionalAccounts/{id}" on page 208

"POST FunctionalAccounts" on page 209

"DELETE FunctionalAccounts/{id}" on page 211

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

…

]

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

207

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

Response codes

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

For more information, please see "Common response codes" on page 17.

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

208

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

FunctionalAccountID : int,

PlatformID: int, DomainName : string,

AccountName : string,

DisplayName : string,

Description : string,

ElevationCommand : string,

SystemReferenceCount : int,

TenantID : string,

ObjectID : 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).

Response codes

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

For more information, please see "Common response codes" on page 17.

POST FunctionalAccounts

Purpose

Creates a functional account.

Required permissions

Password Safe Account Management (Read/Write).

Request body

Content-Type: application/json

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

209

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

PlatformID : int,

DomainName : string,

AccountName : string,

DisplayName : string,

Password : string,

PrivateKey : string,

Passphrase : string,

Description : string,

ElevationCommand : string,

TenantID : string,

ObjectID : string,

Secret : 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 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 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.

Response body

Content-Type: application/json

{

FunctionalAccountID : int,

PlatformID : int,

DomainName : string,

AccountName : string,

DisplayName : string,

Description : string,

ElevationCommand : string,

SystemReferenceCount : int,

TenantID : string,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

210

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

ObjectID : 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).

Response codes

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

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

211

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Request body

None.

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

212

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

ISA requests

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

For more information on Requestor and Requestor/Approver role access, please see "POST Requests" on page 380.

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

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

213

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

214

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

ISA sessions

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

For more information on Requestor and Requestor/Approver role access, please see the following:

"POST Requests" on page 380

"POST Requests/{requestID}/Sessions" on page 404

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

215

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

216

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Keystrokes

Quick navigation

"GET Sessions/{sessionId:int}/Keystrokes" on page 217

"GET Keystrokes/{id:long}" on page 218

"POST Keystrokes/Search" on page 218

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

217

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

POST Keystrokes/Search

Purpose

Search for keystrokes.

Required roles

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

218

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

219

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

Quick navigation

"GET ManagedSystems/{systemID}/LinkedAccounts" on page 220

"POST ManagedSystems/{systemID}/LinkedAccounts/{accountID}" on page 223

"DELETE ManagedSystems/{systemID}/LinkedAccounts" on page 225

"DELETE ManagedSystems/{systemID}/LinkedAccounts/{accountID}" on page 226

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

220

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

221

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see Configure Subscriber Accounts at https://www.beyondtrust.com/docs/beyondinsight-

password-safe/ps/admin/managed-accounts.htm#ConfigureAccounts.

Response codes

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

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

222

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

223

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

224

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see Configure Subscriber Accounts at https://www.beyondtrust.com/docs/beyondinsight-

password-safe/ps/admin/managed-accounts.htm#ConfigureAccounts.

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.

For more information, please see "Common response codes" on page 17.

DELETE ManagedSystems/{systemID}/LinkedAccounts

Purpose

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

Required permissions

Password Safe System Management (Read/Write).

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

225

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

URL parameters

systemID: ID of the managed system.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

226

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Response codes

200 - Request successful.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

227

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

"GET ManagedAccounts" on page 228

"GET ManagedAccounts?systemName={systemName}&accountName={accountName}" on page 232

For more information on related topics, please see:

"Managed systems" on page 287

"Requests" on page 379

"Quick rules" on page 367

"Smart Rules" on page 110

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

228

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

229

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

230

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see the following:

"ISA requests" on page 213

"ISA sessions" on page 215

"POST Requests" on page 380

"Credentials" on page 182

"POST Requests/{requestID}/Sessions" on page 404

Response codes

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

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

231

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "GET ManagedAccounts" on page 228.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

232

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

Provisioning

Quick navigation

"GET ManagedAccounts/{id}" on page 234

"GET ManagedSystems/{systemID}/ManagedAccounts" on page 237

"GET ManagedSystems/{systemID}/ManagedAccounts?name={name}" on page 240

"PUT ManagedAccounts/{id}" on page 243

"POST ManagedSystems/{systemID}/ManagedAccounts" on page 251

"DELETE ManagedAccounts/{id}" on page 261

"DELETE ManagedSystems/{systemID}/ManagedAccounts/{accountName}" on page 262

"DELETE ManagedSystems/{id}/ManagedAccounts" on page 263

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

233

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

234

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

235

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

For more information, please see Configure Subscriber Accounts at https://www.beyondtrust.com/docs/beyondinsight-

password-safe/ps/admin/managed-accounts.htm#ConfigureAccounts.

Response code

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

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

236

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

237

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

238

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see Configure Subscriber Accounts at https://www.beyondtrust.com/docs/beyondinsight-

password-safe/ps/admin/managed-accounts.htm#ConfigureAccounts.

Response codes

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

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

239

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

240

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

241

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see Configure Subscriber Accounts at https://www.beyondtrust.com/docs/beyondinsight-

password-safe/ps/admin/managed-accounts.htm#ConfigureAccounts.

Response codes

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

242

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

}

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

243

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

244

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

245

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

246

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

247

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

248

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

249

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

For more information, please see "Common response codes" on page 17.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

250

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

251

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

252

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

253

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

254

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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,

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

255

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

256

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

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

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

257

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

{

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.

SALES: www.beyondtrust.com/contact

SUPPORT: www.beyondtrust.com/support

DOCUMENTATION: www.beyondtrust.com/docs

258

depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 9/4/2024

BEYONDINSIGHT AND PASSWORD SAFE 24.2

API GUIDE

SAMAccountName: (Active Directory managed systems, optional for Entra ID managed systems) The account SAM account

name of an Active Directory account.