Password Safe and BeyondInsight API Guide...POSTOracleInternetDirectories/{id}/Test 151 DSSKeyPolicies 152 GETDSSKeyRules 152 GETDSSKeyRules/{id} 153 EntityTypes 155 GETEntityTypes

BeyondInsight and Password SafeAPI Guide 7.2

©2003-2020 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depositoryinstitution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC:12/10/2020

Table of Contents

BeyondInsight and Password Safe API Overview 12

Usage 13

API Key 13

Session State 13

Base Endpoint 13

Authorization Header 13

Two-Factor Authentication 14

Common Response Codes 14

Examples 15

Workflow 17

Authentication 19

POST Auth/SignAppin 19

POST Auth/Signout 20

Entity Relationship Diagram 21

BeyondInsight APIs 22

Access Levels 23

GET AccessLevels 23

Get AccessLevels 23

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

Address Groups 25

GET Organizations/{orgID}/addressgroups 25

GET Addressgroups 26

GET Addressgroups/{addressGroupId}/addresses 27

POST AddressGroups/{id}/Addresses 27

DELETE Addressgroups/{addressGroupId} 28

DELETE Addressgroups/{addressGroupId}/addresses 29

GET AddressGroups/?name={name} 29

GET AddressGroups/{id} 30

PUT Addresses/{id} 31

PUT AddressGroups/{id} 32

POST AddressGroups 32

SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 2©2003-2020 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depositoryinstitution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.

TC: 12/10/2020

BEYONDINSIGHT AND PASSWORD SAFE

API GUIDE 7.2

This page needed for table ofcontents. Do not delete.

GET Addresses/{id} 33

DELETE Addresses/{id} 34

Assets 35

GET Assets/{id} 35

GETWorkgroups/{workgroupID}/Assets 36

GETWorkgroups/{workgroupName}/Assets 37

GETWorkgroups/{workgroupName}/Assets?name={name} 39

POSTWorkgroups/{workgroupID}/Assets 40

POSTWorkgroups/{workgroupName}/Assets 41

PUT Assets/{id} 42

POST Assets/Search 44

DELETE Assets/{id} 46

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

Smart Rule Assets 47

GET SmartRules/{id}/Assets 47

Attribute Types 49

GET AttributeTypes 49

GET AttributeTypes/{id} 49

POST AttributeTypes 50

DELETE AttributeTypes/{id} 51

Attributes 52

GET AttributeTypes/{attributeTypeID}/Attributes 52

GET Attributes/{id} 53

POST AttributeTypes/{attributeTypeID}/Attributes 54

DELETE Attributes/{id} 55

Asset Attributes 57

GET Assets/{assetID}/Attributes 57

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

DELETE Assets/{assetID}/Attributes 58

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

Configuration 60

GET Configuration/Version 60

Databases 61


TC: 12/10/2020


API GUIDE 7.2


GET Databases 61

GET Databases/{id} 62

GET Assets/{id}/Databases 63

POST Assets/{id}/Databases 63

PUT Databases/{id} 65

DELETE Databases/{id} 66

Environmental Metrics 67

GET SmartRules/{id}/EnvironmentalMetrics 67

Imports 68

POST Imports 68

Operating Systems 70

GET OperatingSystems 70

Organizations 71

GET Organizations 71

GET Organizations/{id} 71

GET Organizations?name={name} 72

Permissions 74

GET Permissions 74

User Group Permissions 75

GET UserGroups/{userGroupID}/Permissions 75

POST UserGroups/{userGroupId}/Permissions 75

DELETE UserGroups/{userGroupId}/Permissions 76

Smart Rules 77

GET SmartRules 77

GET SmartRules/{id} 78

GET SmartRules?title={title} 79

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

POST SmartRules/FilterAssetAttribute 81

POST SmartRules/{id}/Process 82

DELETE SmartRules/{id} 82

DELETE SmartRules?title={title} 83

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

User Groups 85


TC: 12/10/2020


API GUIDE 7.2


GET UserGroups 85

GET UserGroups/{id} 86

GET UserGroups?name={name} 86

POST UserGroups 87

DELETE UserGroups/{id} 90

DELETE UserGroups?name={name} 91

User Group Memberships 92

GET Users/{userID}/UserGroups 92

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

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

Users 95

GET Users 95

GET UserGroups/{userGroupId}/Users 96

GET Users/{id} 97

POST Users 98

POST Users/{id}/Quarantine 100

POST UserGroups/{userGroupId}/Users 101

PUT Users/{id} 102

DELETE Users/{id} 103

Vulnerabilities 104

GET Assets/{id}/Vulnerabilities?smartRuleID={srID} 104

Vulnerabilities Export Report 107

POST Vulnerabilities/ExportReport 107

Vulnerability References 110

GET Vulnerabilities/{id}/VulnerabilityReferences 110

Workgroups 111

GETWorkgroups 111

GETWorkgroups/{id} 111

GETWorkgroups?name={name} 112

POSTWorkgroups 113

Deprecated 115

Password Safe APIs 121

Access Policies 121


TC: 12/10/2020


API GUIDE 7.2


GET AccessPolicies 121

POST AccessPolicies/Test 122

Aliases 124

GET Aliases 124

GET Aliases/{id} 125

GET Aliases?name={name} 126

Applications 128

GET Applications 128

GET Applications/{id} 129

Managed Account Applications 130

GET ManagedAccounts/{accountID}/Applications 130

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

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

DELETE ManagedAccounts/{accountID}/Applications 132

Attributes 134

GET ManagedAccounts/{managedAccountID}/Attributes 134

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

DELETE ManagedAccounts/{managedAccountID}/Attributes 136

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

Credentials 138

GET Credentials/{requestId} 138

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

Managed Account Credentials 141

PUT ManagedAccounts/{managedAccountID}/Credentials 141

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

POST ManagedAccounts/{managedAccountID}/Credentials/Test 143

POST ManagedAccounts/{managedAccountID}/Credentials/Change 144

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

Directories 146

GET Directories 146

GET Directories/{id} 147

POSTWorkgroups/{id}/Directories 148


TC: 12/10/2020


API GUIDE 7.2


PUT Directories/{id} 150

DELETE Directories 153

Oracle Internet Directories 154

GET OracleInternetDirectories 154

GET OracleInternetDirectories/{id} 154

GET Organizations/{id}/OracleInternetDirectories 155

POST OracleInternetDirectories/{id}/Services/Query 156

POST OracleInternetDirectories/{id}/Test 157

DSS Key Policies 158

GET DSSKeyRules 158

GET DSSKeyRules/{id} 159

Entity Types 161

GET EntityTypes 161

Functional Accounts 162

GET FunctionalAccounts 162

GET FunctionalAccounts/{id} 163

GET FunctionalAccounts/{id}/ManagedSystems 164

POST FunctionalAccounts 167

DELETE FunctionalAccounts/{id} 168

ISA Requests 170

POST ISARequests 170

ISA Sessions 172

POST ISASessions 172

Keystrokes 174

GET Sessions/{sessionId:int}/Keystrokes 174

GET Keystrokes/{id:long} 174

POST Keystrokes/Search 175

Linked Accounts 177

GET ManagedSystems/{systemID}/LinkedAccounts 177

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

DELETE ManagedSystems/{systemID}/LinkedAccounts 181

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

Managed Accounts 184


TC: 12/10/2020


API GUIDE 7.2


GETManagedAccounts 184

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

Provisioning 188

GET ManagedAccounts/{id} 188

GET ManagedSystems/{systemID}/ManagedAccounts 190

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

PUT ManagedAccounts/{id} 195

POST ManagedSystems/{systemID}/ManagedAccounts 200

DELETE ManagedAccounts/{id} 206

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

DELETE ManagedSystems/{id}/ManagedAccounts 207

Quick Rule Managed Accounts 209

GET QuickRules/{quickRuleID}/ManagedAccounts 209

PUT QuickRules/{quickRuleID}/ManagedAccounts 211

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

Smart Rule Managed Accounts 220

GET SmartRules/{smartRuleID}/ManagedAccounts 220

Managed Systems 223

GET ManagedSystems 223

GET ManagedSystems/{id} 226

GET Assets/{assetId}/ManagedSystems 228

GET Databases/{databaseID}/ManagedSystems 229

GET FunctionalAccounts/{id}/ManagedSystems 231

GETWorkgroups/{id}/ManagedSystems 234

PUT ManagedSystems/{id} 237

POST Assets/{assetId}/ManagedSystems 240

POST Databases/{databaseID}/ManagedSystems 243

POSTWorkgroups/{id}/ManagedSystems 246

DELETE ManagedSystems/{id} 249

Smart Rule Managed Systems 252

GET SmartRules/{id}/ManagedSystems 252

Nodes 255


TC: 12/10/2020


API GUIDE 7.2


GET Nodes 255

Password Policies 257

GET PasswordRules 257

GET PasswordRules/{id} 258

Platforms 260

GET Platforms 260

GET Platforms/{id} 261

GET EntityTypes/{id}/Platforms 262

Quick Rules 265

POST QuickRules 265

GET QuickRules 266

GET QuickRules/{id} 267

GET QuickRules?title={title} 268

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

DELETE QuickRules/{id} 269

DELETE QuickRules?title={title} 270

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

Replay 272

POST pbsm/replay 272

GET pbsm/replay/{replayId} 273

PUT pbsm/replay/{replayId} 274

DELETE pbsm/replay/{replayId} 275

Requests 276

GET Requests 276

POST Requests 277

POST Aliases/{aliasId}/Requests 279

PUT Requests/{id}/Checkin 281

PUT Requests/{id}/Approve 282

PUT Requests/{id}/Deny 282

PUT Requests/{id}/RotateOnCheckin 283

Request Termination 285

POST ManagedAccounts/{managedAccountID}/Requests/Terminate 285

POST ManagedSystems/{managedSystemID}/Requests/Terminate 286


TC: 12/10/2020


API GUIDE 7.2


POST Users/{userID}/Requests/Terminate 286

Request Sets 288

GET RequestSets 288

POST RequestSets 289

Roles 292

GET Roles 292

User Group Roles 293

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

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

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

Sessions 296

GET Sessions 296

GET Sessions/{id} 297

POST Requests/{requestID}/Sessions 298

POST Sessions/Admin 300

Session Locking 303

POST Sessions/{sessionID}/Lock 303

POST ManagedAccounts/{managedAccountID}/Sessions/Lock 303

POST ManagedSystems/{managedSystemID}/Sessions/Lock 304

Session Termination 305

POST Sessions/{sessionID}/Terminate 305

POST ManagedAccounts/{managedAccountID}/Sessions/Terminate 305

POST ManagedSystems/{managedSystemID}/Sessions/Terminate 306

Synced Accounts 307

GET ManagedAccounts/{id}/SyncedAccounts 307

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

DELETE ManagedAccounts/{id}/SyncedAccounts 311

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

Ticket Systems 313

GET TicketSystems 313

Deprecated 314

Appendix 319

Migration from v1 or v2 319


TC: 12/10/2020


API GUIDE 7.2


Authorization Header 319

Endpoint Comparison 319

Endpoint Mapping 319


TC: 12/10/2020


API GUIDE 7.2


BeyondInsight and Password Safe API OverviewThis document specifies the Representational State Transfer (REST) compliant Application Programmer Interface (API) over HTTPSfor BeyondInsight and Password Safe. It is a way to integrate a portion of the BeyondInsight and Password Safe functionality into yourown applications.

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

For more information about enabling API Access, please see the following:l BeyondInsight User Guide at https://www.beyondtrust.com/docs/beyondinsight-password-safe/bi/index.html Password Safe Admin Guide at https://www.beyondtrust.com/docs/beyondinsight-password-safe/ps/index.htm


TC: 12/10/2020


API GUIDE 7.2

https://www.beyondtrust.com/docs/beyondinsight-password-safe/bi/index.htmhttps://www.beyondtrust.com/docs/beyondinsight-password-safe/bi/index.htmhttps://www.beyondtrust.com/docs/beyondinsight-password-safe/ps/index.htmhttps://www.beyondtrust.com/docs/beyondinsight-password-safe/ps/index.htm

Usage

API Key

The API key is a cryptographically strong random sequence of numbers hashed into a 128-character string. It is encrypted and storedinternally using AES 256 encryption. Any language with a Representational State Transfer (REST) compliant interface can access theAPI with the API key and Run As 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 will produce 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 APIPOST Auth/SignAppIn and always call POST Auth/Signout when you are done.

Base Endpoint

The following base endpoint will be used throughout this document. the-server is a placeholder and should be replaced for yourenvironment. SSL is required to use the Password Safe Public API.

= https://the-server/BeyondTrust/api/public/v3

IMPORTANT!

The base endpoint has changed as of v6.2.0. The previous endpoint (https://the-server/eEye.RetinaCS.Server/api/public/v3) willcontinue to accept API calls, however new scripts should use the new endpoint above and existing scripts should be changed atthe earliest opportunity after upgrading to v6.2.0 (or above). This change decouples the API from BeyondInsight and PasswordSafe, isolating resources and allowing standalone API configuration.

Authorization Header

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

l key: The API Key configured in BeyondInsight for your application.l runas: The username of a BeyondInsight user that has been granted permission to use the API Key.l 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.


TC: 12/10/2020


API GUIDE 7.2

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 notrequired. The first call to POST Auth/SignAppIn should log the user in, as long as the authentication request to the two-factor serverdoes not time out.

Challenge

When a two-factor challenge is configured, two calls to POST Auth/SignAppIn are required and session state must be maintainedbetween 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-2FAcontaining the prompt from the authentication service. The prompt can be used to prompt the user for the challenge answer.

Note: If this 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 theauthorization header, similar to the other authorization parameters:

l 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 subsequentrequests.

Common Response Codes

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

l 200 – Request successful.l 204 – Request successful. No content in body.l 400 – Bad Request – Validation failure or missing request body. Reason in response body.l 401 – Unauthorized – User is not authenticated. Typical reasons include:

o An invalid product license was detected.o The request headers were not set properly.o The server could not verify the validity of the request (due to one or more API factors).o The user session has expired.o 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 will be created in BeyondInsightand an email will be sent to the Administrator detailing the reason. Look here first for the reason why authorization failed.

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


TC: 12/10/2020


API GUIDE 7.2

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

l 404 – Object not found where expected. Reason in response body.l 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("/Auth/SignAppin", content).Result;

Subsequent calls:

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

User Password Factor Enabled (header example only)

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 = "/Auth/SignAppin";$signinResult = Invoke-RestMethod -Uri $uri -Method POST -Headers $headers -SessionVariablescript:session;

Subsequent calls:

$uri = "/ManagedAccounts";$accounts = Invoke-RestMethod -Uri $uri -Method GET -WebSession $script:session -Headers $headers;


TC: 12/10/2020


API GUIDE 7.2

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: '/Auth/SignAppin', :headers =>{‘Authorization’ => samp_key} )session_id = result.cookies["ASP.NET_SessionId"]

Subsequent calls:

result = RestClient::Request.execute(method: :get, url: '/ManagedAccounts', :headers=>{‘Authorization’ => samp_key, :cookies => {'ASP.NET_SessionId' => session_id}} )

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('/Auth/SignAppin')

Subsequent calls:

accounts = session.get('/ManagedAccounts')

Example: Bash

Using curl, option –c will create cookie file and –b will use it in subsequent API calls.

curl -i -c pbpscookie.txt -X POST https:/Auth/SignAppin -H "Content-Type: application/json" -H"Authorization: PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe;" -d ""

Subsequent calls:


TC: 12/10/2020


API GUIDE 7.2

curl -i -b pbpscookie.txt -X GET https:/ManagedAccounts -H "Content-Type: application/json" -H"Authorization: PS-Auth key=c479a66f…c9484d; runas=doe-main\johndoe;" -d ""

Workflow

There are some loose dependencies between the APIs. A typical sequence will be to list accounts or find an account, request apassword, 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 anLDAP/AD/BeyondInsight User Group, grant Read access to new smart rule with Requestor role and access policy.

l POST /Auth/SignAppin

l POST /Workgroups/{ID}/Assets

l POST /Assets/{assetId}/ManagedSystems

l POST /ManagedSystems/{managedSystemId}/ManagedAccounts

l POST /QuickRules

l POST /UserGroups

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

l POST /Auth/Signout

Retrieve a Password

Case: Request, Retrieve, and Checkin a password for a managed account


l GET /ManagedAccounts OR GET /ManagedAccounts?systemName={systemName}&accountName={accountName}

l POST /Requests

l GET /Credentials/{requestId}

l PUT /Requests/{requestId}/Checkin


Create a Session

Case: Request a Session, Create a Session, and Checkin the request for a managed account



l POST /Requests (AccessType="RDP" or AccessType="SSH")

l POST /Requests/{requestId}/Sessions (SessionType == Request.AccessType above)


TC: 12/10/2020


API GUIDE 7.2

l PUT /Requests/{requestId}/Checkin


Retrieve a Password as an ISA

Case: Create an ISA Password Request



l POST /ISARequests


Create a Session as an ISA

Case: Create an ISA Session



l POST /ISASessions



TC: 12/10/2020


API GUIDE 7.2

Authentication

Quick Navigation

l POST Auth/SignAppinl POST Auth/Signout

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 scriptfrom 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

l 200 – Request successful. User model in the response body.l 403 – Access forbidden. Returned if the Password Safe license is not valid.l 410 – API version has been disabled.

For more information, please see "Common Response Codes" on page 14.


TC: 12/10/2020


API GUIDE 7.2

POST Auth/Signout

Purpose

Terminates the current user session.


None

Request Body

None

Response Body

None

Response Codes

l 200 – Request successful.



TC: 12/10/2020


API GUIDE 7.2

Entity Relationship Diagram


TC: 12/10/2020


API GUIDE 7.2

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


TC: 12/10/2020


API GUIDE 7.2

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

Quick Navigationl

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

GET AccessLevels

Purpose

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


User Accounts Management (Read)

Request Body

None

Response Body


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

Response Codes

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


Get AccessLevels

Purpose

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


TC: 12/10/2020


API GUIDE 7.2

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

Purpose

Sets the Access Level for a User Group Smart Rule.


l User Accounts Management (Read/Write)

URL Parameters

l userGroupId: ID of the user group.l smartRuleId: ID of the smart rule.

Request Body


{AccessLevelID: int}

Response Body

None

Response Codes

l 200 - Request successful.



TC: 12/10/2020


API GUIDE 7.2

Address Groups

Quick Navigation

l GET Organizations/{orgID}/addressgroupsl "GET Addresses/{id}" on page 33l GET Addressgroupsl "GET AddressGroups/{id}" on page 30l GET Addressgroups/{addressGroupId}/addressesl "GET AddressGroups/?name={name}" on page 29l "POST AddressGroups/{id}/Addresses" on page 27l "POST AddressGroups" on page 32l "DELETE Addresses/{id}" on page 34l DELETE Addressgroups/{addressGroupId}l DELETE Addressgroups/{addressGroupId}/addressesl "PUT Addresses/{id}" on page 31l "PUT AddressGroups/{id}" on page 32

GET Organizations/{orgID}/addressgroups

Purpose

List the address groups for a given organization.


l Current user has access to the organization.l Asset Management (Read)

URL Parameters

orgId: Organization ID.

Request Body

None

Response Body


[{

AddressGroupID: int,Name: string,


TC: 12/10/2020


API GUIDE 7.2

OrganizationID: guid // can be null}

]

Response Codes

200 - Request successful


GET Addressgroups

Purpose

List the address groups.



URL Parameters

None

Request Body

None

Response Body


[{

AddressGroupID: int,Name: string,OrganizationID: guid // can be null

{]

Response Codes




TC: 12/10/2020


API GUIDE 7.2

GET Addressgroups/{addressGroupId}/addresses

Purpose

List the addresses for an address group.



URL Parameters

addressGroupId: Address Group ID.

Request Body

None

Response Body


[{AddressID: int,AddressGroupID: int,Omit: boolean,Type: string,Value: string,LastUpdatedDate: datetime

}]

Response Codes



POST AddressGroups/{id}/Addresses

Purpose

Create an address in an Address Book.


l Asset Management (Read/Write)


TC: 12/10/2020


API GUIDE 7.2

URL Parameters


Request Body

{Type: int,Value: string,Omit: bool}

Response Body


{AddressID: int,AddressGroupID: int,Omit: bool,Type: int,Value: string,LastUpdatedDate: datetime

}

Response Codes

201 - Request successful. Address in the response body.


DELETE Addressgroups/{addressGroupId}

Purpose

Delete the address group and all it's addresses.


l Current user has access to the organization.l Asset Management (Read/Write)

URL Parameters


Request Body

None


TC: 12/10/2020


API GUIDE 7.2

Response Body

None

Response Codes



DELETE Addressgroups/{addressGroupId}/addresses

Purpose

Delete the addresses within the address group.


l Current user has access to the organization.l Asset Management (Read/Write)

URL Parameters


Request Body

None

Response Body

None

Response Codes



GET AddressGroups/?name={name}

Purpose

Returns the Address Group by name.


l Asset Management (Read)


TC: 12/10/2020


API GUIDE 7.2

Query Parameters

name: Name of the Address Group.

Request Body

None.

Response Body


{AddressGroupID: int,Name: string

}

Response Codes

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


GET AddressGroups/{id}

Purpose

Returns the Address Group by ID.



URL Parameters

id: ID of the Address Group.

Request Body

None.

Response Body



}


TC: 12/10/2020


API GUIDE 7.2

Response Codes



PUT Addresses/{id}

Purpose

Updates and Address by ID.



Request Body


{Type: int,Value: string,Omit: bool

}

Response Body


{AddressD: int,AddressGroupID: int,Omit: bool,Type: int,Value: string,LastUpdateDate: datetime

}

Response Codes




TC: 12/10/2020


API GUIDE 7.2

PUT AddressGroups/{id}

Purpose

Updates and Address Group by ID.



Request Body


{Name: string,

}

Response Body



}

Response Codes



POST AddressGroups

Purpose

Creates an Address Book.



Request Body



TC: 12/10/2020


API GUIDE 7.2

{Name: string

}

Response Body



}

Response Codes



GET Addresses/{id}

Purpose

Returns the Address by ID.



URL Parameters

id: ID of the Address

Request Body

None

Response Body


{AddressId: int,AddressGroupId : int,Omit: bool,Type: string,Value: string,LastUpdateDate: datetime

}


TC: 12/10/2020


API GUIDE 7.2

Response Codes



DELETE Addresses/{id}

Purpose

Deletes an Address by ID.


Asset Management (Read/Write)

Request Body

None

Response Body

None

Response Codes

200 - Request successful.



TC: 12/10/2020


API GUIDE 7.2

Assets

Quick Navigation

l GET Assets/{id}l GETWorkgroups/{workgroupID}/Assetsl GETWorkgroups/{workgroupName}/Assetsl GETWorkgroups/{workgroupName}/Assets?name={name}l POSTWorkgroups/{workgroupID}/Assetsl POSTWorkgroups/{workgroupName}/Assetsl PUT Assets/{id}l POST Assets/Searchl DELETE Assets/{id}

For more information on related topics, please see:

l Workgroupsl Smart Rulesl Vulnerabilitiesl Managed Systems

GET Assets/{id}

Purpose

Returns an Asset by ID.


Asset Management (Read)

URL Parameters

id: ID of the asset.

Request Body

None

Response Body



TC: 12/10/2020


API GUIDE 7.2

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


GET Workgroups/{workgroupID}/Assets

Purpose

Returns a list of Assets by Workgroup ID.



URL Parameters

workgroupID: ID of the Workgroup.

Query Parameters (optional)

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

Request Body

None

Response Body (when limit is not given)


[{


TC: 12/10/2020


API GUIDE 7.2

WorkgroupID: int,AssetID: int,AssetName: string,DnsName: string,DomainName: string,IPAddress: string,MacAddress: string,AssetType: string,OperatingSystem: string,CreateDate: datetime,LastUpdateDate: datetime},…]

Response Body (when limit is given)


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


GET Workgroups/{workgroupName}/Assets

Purpose

Returns a list of Assets by Work Group Name.


TC: 12/10/2020


API GUIDE 7.2



URL Parameters

workgroupName: Name of the Workgroup.


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

Request Body

None







[{WorkgroupID: int,AssetID: int,AssetName: string,DnsName: string,DomainName: string,IPAddress: string,


TC: 12/10/2020


API GUIDE 7.2

MacAddress: string,AssetType: string,OperatingSystem: string,CreateDate: datetime,LastUpdateDate: datetime},…]

}

Response Codes



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

Purpose

Returns an Asset by Workgroup Name and Asset Name.



URL Parameters

workgroupName: Name of the workgroup.

Query Parameters

name: Name of the asset.

Request Body

None

Response Body


{WorkgroupID: int,AssetID: int,AssetName: string,DnsName: string,DomainName: string,IPAddress: string,MacAddress: string,


TC: 12/10/2020


API GUIDE 7.2

AssetType: string,OperatingSystem: string,CreateDate: datetime,LastUpdateDate: datetime}

Response Codes



POST Workgroups/{workgroupID}/Assets

Purpose

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



URL Parameters

workgroupID: ID of the workgroup.

Request Body


{IPAddress: string,AssetName: string,DnsName: string,DomainName: string,MacAddress: string,AssetType: string,OperatingSystem: string}

Request Body Details

l IPAddress: (required) Asset IP address.l AssetName: (optional) Asset name. If not given, a padded IPAddress is used.l DnsName: (optional) Asset DNS name.l DomainName: (optional) Asset domain name.l MacAddress: (optional) Asset MAC address.


TC: 12/10/2020


API GUIDE 7.2

l AssetType: (optional) Asset type.l OperatingSystem: (optional) Asset operating system.

Response Body



Response Codes



POST Workgroups/{workgroupName}/Assets

Purpose

Creates a new asset in the workgroup referenced by name.



URL Parameters


Request Body


{IPAddress: string,AssetName: string,DnsName: string,DomainName: string,


TC: 12/10/2020


API GUIDE 7.2

MacAddress: string,AssetType: string,OperatingSystem: string}


l IPAddress: (required) Asset IP address.l AssetName: (optional) Asset name. If not given, a padded IPAddress is used.l DnsName: (optional) Asset DNS name.l DomainName: (optional) Asset domain name.l MacAddress: (optional) Asset MAC address.l AssetType: (optional) Asset type.l OperatingSystem: (optional) Asset operating system.

Response Body



Response Codes



PUT Assets/{id}

Purpose

Updates an existing asset by ID.


TC: 12/10/2020


API GUIDE 7.2

Tip: Call "GET Assets/{id}" on page 35 (or equivalent) first to get the current state of the Asset before calling PUT Assets/{id} to update it with new values.



URL Parameters


Request Body


{WorkgroupID: int,AssetName: string,DnsName: string,DomainName: string,IPAddress: string,MacAddress: string,AssetType: string,OperatingSystem: string,}


l WorkgroupID: (required) ID of the Workgroup to which the asset belongs.l AssetName: (required) Asset name.l DnsName: (required) Asset DNS name.l DomainName: (required) Asset domain name.l IPAddress: (required) Asset IP address.l MacAddress: (required) Asset MAC address. An empty value is accepted and will clear any existing value.l AssetType: (required) Asset type. An empty value is accepted and will clear any existing value.l OperatingSystem: (required) Asset operating system. An empty value is accepted and will clear any existing value.

Response Body


{WorkgroupID: int,AssetID: int,AssetName: string,DnsName: string,DomainName: string,IPAddress: string,


TC: 12/10/2020


API GUIDE 7.2

MacAddress: string,AssetType: string,OperatingSystem: string,CreateDate: datetime,LastUpdateDate: datetime}

Response Codes



POST Assets/Search

Purpose

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




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

Request Body


{AssetName: string,DnsName: string,DomainName: string,IPAddress: string,MacAddress: string,AssetType: string,}


At least one request body property should be provided; any property not provided will be ignored. All search criteria is caseinsensitive 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).


TC: 12/10/2020


API GUIDE 7.2








}

Response Codes




TC: 12/10/2020


API GUIDE 7.2

DELETE Assets/{id}

Purpose

Deletes an Asset by ID.



URL Parameters


Request Body

None

Response Body

None

Response Codes



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

Purpose

Deletes an Asset by Workgroup Name and Asset Name.



URL Parameters


Query Parameters

name: Name of the asset.

Request Body

None


TC: 12/10/2020


API GUIDE 7.2

Response Body

None

Response Codes



Smart Rule Assets

GET SmartRules/{id}/Assets

Purpose

Returns a list of Assets by Smart Rule ID.


Read access to the smart rule referenced by ID.

URL Parameters

id: ID of the Smart Rule.


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

Request Body

None



[{WorkgroupID: int,AssetID: int,AssetName: string,DnsName: string,DomainName: string,IPAddress: string,MacAddress: string,AssetType: string,


TC: 12/10/2020


API GUIDE 7.2

OperatingSystem: string,CreateDate: datetime,LastUpdateDate: datetime},…]





}

Response Codes




TC: 12/10/2020


API GUIDE 7.2

Attribute Types

Quick Navigation

l "GET AttributeTypes" on page 49l "GET AttributeTypes/{id}" on page 49l "POST AttributeTypes" on page 50l "DELETE AttributeTypes/{id}" on page 51

GET AttributeTypes

Purpose

Returns a list of Attribute Types.


Attribute Management (Read)

Request Body

None

Response Body


[{AttributeTypeID : int,Name : string,IsReadOnly: bool},…]

Response Codes

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


GET AttributeTypes/{id}

Purpose

Returns an Attribute Type by ID.


TC: 12/10/2020


API GUIDE 7.2



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.


POST AttributeTypes

Purpose

Creates a new Attribute Type.


Attribute Management (Read/Write)

Request Body


{Name : string}

Response Body

Content-type: application/json


TC: 12/10/2020


API GUIDE 7.2

{AttributeTypeID : int,Name : string,IsReadOnly: bool}

Response Codes

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


DELETE AttributeTypes/{id}

Purpose

Deletes an Attribute Type and all related Attributes by ID.



URL Parameters

id: ID of the Attribute Type.

Request Body

None

Response Body

None

Response Codes

200 – Request successful.



TC: 12/10/2020


API GUIDE 7.2

Attributes

Quick Navigation

l GET AttributeTypes/{attributeTypeID}/Attributesl GET Attributes/{id}l POST AttributeTypes/{attributeTypeID}/Attributesl DELETE Attributes/{id}

GET AttributeTypes/{attributeTypeID}/Attributes

Purpose

Returns a list of attribute definitions by Attribute Type.



URL Parameters

attributeTypeID: ID of the Attribute Type.

Request Body

None

Response Body


[{AttributeID : int,AttributeTypeID : int,ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool,ChildAttributes :

[{AttributeID : int,AttributeTypeID : int,ParentAttributeID : int,ShortName : string,LongName : string,Description : string,


TC: 12/10/2020


API GUIDE 7.2

ValueInt : int, // can be nullIsReadOnly: bool,},…]

},…]

Response Codes

200 – Request successful. Attributes in the response body.


GET Attributes/{id}

Purpose

Returns an attribute definition by ID.



URL Parameters

id: ID of the Attribute.

Request Body

None

Response Body


{AttributeID : int,AttributeTypeID : int,ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool,ChildAttributes :

[{AttributeID : int,


TC: 12/10/2020


API GUIDE 7.2

AttributeTypeID : int,ParentAttributeID : int,ShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool,},…]

}

Response Codes



POST AttributeTypes/{attributeTypeID}/Attributes

Purpose

Creates a new attribute definition by Attribute Type ID.



URL Parameters

attributeTypeID: ID of the Attribute Type.

Request Body


{ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int // can be null}

Response Body



TC: 12/10/2020


API GUIDE 7.2

{AttributeID : int,AttributeTypeID : int,ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool,ChildAttributes :

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

}

Response Codes



DELETE Attributes/{id}

Purpose

Deletes an attribute definition by ID.



URL Parameters

id: ID of the Attribute.

Request Body

None

Response Body

None


TC: 12/10/2020


API GUIDE 7.2

Response Codes




TC: 12/10/2020


API GUIDE 7.2

Asset Attributes

Quick Navigation

l GET Assets/{assetID}/Attributesl POST Assets/{assetID}/Attributes/{attributeID}l DELETE Assets/{assetID}/Attributesl DELETE Assets/{assetID}/Attributes/{attributeID}

GET Assets/{assetID}/Attributes

Purpose

Returns a list of attributes by Asset ID.


Asset Management (Read), Attribute Management (Read)

URL Parameters

assetID: ID of the Asset.

Request Body

None

Response Body


[{AttributeID : int, AttributeTypeID : int,ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool},…]

Response Codes

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


TC: 12/10/2020


API GUIDE 7.2


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

Purpose

Assigns an attribute to an Asset.


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

URL Parameters

l assetID: ID of the asset.l attributeID: ID of the attribute Request Body.

Response Body


{AttributeID : int, AttributeTypeID : int,ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool,}

Response Codes



DELETE Assets/{assetID}/Attributes

Purpose

Deletes all asset attributes by Asset ID.


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


TC: 12/10/2020


API GUIDE 7.2

URL Parameters

assetID: ID of the Asset.

Request Body

None

Response Body

None

Response Codes



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

Purpose

Deletes an asset attribute by Asset ID and Attribute ID.


l Asset Management (Read/Write)l Attribute Management (Read/Write)

URL Parameters

assetID: ID of the Asset attributeID and ID of the Attribute.

Request Body

None

Response Body

None

Response Codes




TC: 12/10/2020


API GUIDE 7.2

Configuration

GET Configuration/Version

Purpose

Returns the current system version.

Request Body

None

Response Body


{Version : string}

Response Codes

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



TC: 12/10/2020


API GUIDE 7.2

Databases

Quick Navigation

l GET Databasesl GET Databases/{id}l GET Assets/{id}/Databasesl POST Assets/{id}/Databasesl PUT Databases/{id}l DELETE Databases/{id}

For more information on related topics, please see:

l Assetsl Platformsl Managed Systems

GET Databases

Purpose

Returns a list of Databases.



Request Body

None

Response Body


[{AssetID: int,DatabaseID : int,PlatformID : int,InstanceName : string,IsDefaultInstance : bool,Port : int,Version : string,Template:string},


TC: 12/10/2020


API GUIDE 7.2

…]

Response Codes

201 – Request successful. Databases in the response body.


GET Databases/{id}

Purpose

Returns a Database by ID.



URL Parameters

id: ID of the Database.

Request Body

None

Response Body


{AssetID:int,DatabaseID : int,PlatformID : int,In

Documents

Password Safe and BeyondInsight API Guide...POSTOracleInternetDirectories/{id}/Test 151 DSSKeyPolicies 152 GETDSSKeyRules 152 GETDSSKeyRules/{id} 153 EntityTypes 155 GETEntityTypes