Password Safe and BeyondInsight API Guide...POSTOracleInternetDirectories/{id}/Test 151...
Transcript of Password Safe and BeyondInsight API Guide...POSTOracleInternetDirectories/{id}/Test 151...
-
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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 3©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 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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 4©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 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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 5©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 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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 6©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.
-
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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 7©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.
-
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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 8©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 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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 9©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.
-
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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 10©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.
-
Authorization Header 319
Endpoint Comparison 319
Endpoint Mapping 319
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 11©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.
-
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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 12©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
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.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 13©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
-
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.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 14©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
-
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;
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 15©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
-
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:
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 16©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
-
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 POST /Auth/SignAppin
l GET /ManagedAccounts OR GET /ManagedAccounts?systemName={systemName}&accountName={accountName}
l POST /Requests
l GET /Credentials/{requestId}
l PUT /Requests/{requestId}/Checkin
l POST /Auth/Signout
Create a Session
Case: Request a Session, Create a Session, and Checkin the request for a managed account
l POST /Auth/SignAppin
l GET /ManagedAccounts OR GET /ManagedAccounts?systemName={systemName}&accountName={accountName}
l POST /Requests (AccessType="RDP" or AccessType="SSH")
l POST /Requests/{requestId}/Sessions (SessionType == Request.AccessType above)
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 17©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
-
l PUT /Requests/{requestId}/Checkin
l POST /Auth/Signout
Retrieve a Password as an ISA
Case: Create an ISA Password Request
l POST /Auth/SignAppin
l GET /ManagedAccounts OR GET /ManagedAccounts?systemName={systemName}&accountName={accountName}
l POST /ISARequests
l POST /Auth/Signout
Create a Session as an ISA
Case: Create an ISA Session
l POST /Auth/SignAppin
l GET /ManagedAccounts OR GET /ManagedAccounts?systemName={systemName}&accountName={accountName}
l POST /ISASessions
l POST /Auth/Signout
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 18©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
-
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.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 19©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
-
POST Auth/Signout
Purpose
Terminates the current user session.
Required Permissions
None
Request Body
None
Response Body
None
Response Codes
l 200 – Request successful.
For more information, please see "Common Response Codes" on page 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 20©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
-
Entity Relationship Diagram
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 21©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
-
BeyondInsight APIsThe 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 22©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
-
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
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 14.
Get AccessLevels
Purpose
Returns a list of access levels for permissions, for example, None, Read, and Read/Write
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 23©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
-
POST UserGroups/{userGroupId}/SmartRules/{smartRuleId}/AccessLevels
Purpose
Sets the Access Level for a User Group Smart Rule.
Required Permissions
l User Accounts Management (Read/Write)
URL Parameters
l userGroupId: ID of the user group.l smartRuleId: ID of the smart rule.
Request Body
Content-Type: application/json
{AccessLevelID: int}
Response Body
None
Response Codes
l 200 - Request successful.
For more information, please see "Common Response Codes" on page 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 24©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
-
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.
Required Permissions
l Current user has access to the organization.l Asset Management (Read)
URL Parameters
orgId: Organization ID.
Request Body
None
Response Body
Content-Type: application/json
[{
AddressGroupID: int,Name: string,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 25©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
-
OrganizationID: guid // can be null}
]
Response Codes
200 - Request successful
For more information, please see "Common Response Codes" on page 14.
GET Addressgroups
Purpose
List the address groups.
Required Permissions
l Current user has access to the organization.l Asset Management (Read)
URL Parameters
None
Request Body
None
Response Body
Content-Type: application/json
[{
AddressGroupID: int,Name: string,OrganizationID: guid // can be null
{]
Response Codes
200 - Request successful
For more information, please see "Common Response Codes" on page 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 26©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
-
GET Addressgroups/{addressGroupId}/addresses
Purpose
List the addresses for an address group.
Required Permissions
l Current user has access to the organization.l 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: string,Value: string,LastUpdatedDate: datetime
}]
Response Codes
200 - Request successful
For more information, please see "Common Response Codes" on page 14.
POST AddressGroups/{id}/Addresses
Purpose
Create an address in an Address Book.
Required Permissions
l Asset Management (Read/Write)
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 27©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
-
URL Parameters
addressGroupId: Address Group ID.
Request Body
{Type: int,Value: string,Omit: bool}
Response Body
Content-Type: application/json
{AddressID: int,AddressGroupID: int,Omit: bool,Type: int,Value: string,LastUpdatedDate: datetime
}
Response Codes
201 - Request successful. Address in the response body.
For more information, please see "Common Response Codes" on page 14.
DELETE Addressgroups/{addressGroupId}
Purpose
Delete the address group and all it's addresses.
Required Permissions
l Current user has access to the organization.l 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 28©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
-
Response Body
None
Response Codes
200 - Request successful
For more information, please see "Common Response Codes" on page 14.
DELETE Addressgroups/{addressGroupId}/addresses
Purpose
Delete the addresses within the address group.
Required Permissions
l Current user has access to the organization.l 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 14.
GET AddressGroups/?name={name}
Purpose
Returns the Address Group by name.
Required Permissions
l Asset Management (Read)
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 29©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
-
Query Parameters
name: Name 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 14.
GET AddressGroups/{id}
Purpose
Returns the Address Group by ID.
Required Permissions
l Asset Management (Read)
URL Parameters
id: ID of the Address Group.
Request Body
None.
Response Body
Content-Type: application/json
{AddressGroupID: int,Name: string
}
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 30©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
-
Response Codes
200 - Request successful. Address Group in the response body.
For more information, please see "Common Response Codes" on page 14.
PUT Addresses/{id}
Purpose
Updates and Address by ID.
Required Permissions
l Asset Management (Read/Write)
Request Body
Content-Type: application/json
{Type: int,Value: string,Omit: bool
}
Response Body
Content-Type: application/json
{AddressD: int,AddressGroupID: int,Omit: bool,Type: int,Value: string,LastUpdateDate: datetime
}
Response Codes
200 - Request successful. Address in the response body.
For more information, please see "Common Response Codes" on page 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 31©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
-
PUT AddressGroups/{id}
Purpose
Updates and Address Group by ID.
Required Permissions
l Asset Management (Read/Write)
Request Body
Content-Type: application/json
{Name: string,
}
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 14.
POST AddressGroups
Purpose
Creates an Address Book.
Required Permissions
l 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 32©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
-
{Name: string
}
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 14.
GET Addresses/{id}
Purpose
Returns the Address by ID.
Required Permissions
l Asset Management (Read)
URL Parameters
id: ID of the Address
Request Body
None
Response Body
Content-Type: application/json
{AddressId: int,AddressGroupId : int,Omit: bool,Type: string,Value: string,LastUpdateDate: datetime
}
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 33©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
-
Response Codes
200 - Request successful. Address in the response body.
For more information, please see "Common Response Codes" on page 14.
DELETE Addresses/{id}
Purpose
Deletes an Address by ID.
Required Permissions
Asset Management (Read/Write)
Request Body
None
Response Body
None
Response Codes
200 - Request successful.
For more information, please see "Common Response Codes" on page 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 34©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
-
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.
Required Permissions
Asset Management (Read)
URL Parameters
id: ID of the asset.
Request Body
None
Response Body
Content-Type: application/json
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 35©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
-
{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 14.
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)
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)
Content-Type: application/json
[{
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 36©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
-
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)
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 14.
GET Workgroups/{workgroupName}/Assets
Purpose
Returns a list of Assets by Work Group Name.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 37©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
-
Required Permissions
Asset Management (Read)
URL Parameters
workgroupName: Name 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 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},…]
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,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 38©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
-
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 14.
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
name: Name 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,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 39©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
-
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 14.
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
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.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 40©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
-
l AssetType: (optional) Asset type.l OperatingSystem: (optional) Asset operating system.
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
201 - Request successful. Asset in response body.
For more information, please see "Common Response Codes" on page 14.
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,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 41©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
-
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.l AssetType: (optional) Asset type.l OperatingSystem: (optional) Asset operating system.
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
201 - Request successful. Asset in response body.
For more information, please see "Common Response Codes" on page 14.
PUT Assets/{id}
Purpose
Updates an existing asset by ID.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 42©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
-
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.
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
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
Content-Type: application/json
{WorkgroupID: int,AssetID: int,AssetName: string,DnsName: string,DomainName: string,IPAddress: string,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 43©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
-
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 14.
POST Assets/Search
Purpose
Returns a list of assets that match the given search criteria.
Required Permissions
Asset Management (Read)
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 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 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).
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 44©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
-
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},…]
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 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 45©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
-
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 14.
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
name: Name of the asset.
Request Body
None
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 46©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
-
Response Body
None
Response Codes
200 - Request successful.
For more information, please see "Common Response Codes" on page 14.
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)
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
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,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 47©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
-
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 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 48©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
-
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.
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 14.
GET AttributeTypes/{id}
Purpose
Returns an Attribute Type by ID.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 49©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
-
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 14.
POST AttributeTypes
Purpose
Creates a new Attribute Type.
Required Permissions
Attribute Management (Read/Write)
Request Body
Content-Type: application/json
{Name : string}
Response Body
Content-type: application/json
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 50©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
-
{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 14.
DELETE AttributeTypes/{id}
Purpose
Deletes an Attribute Type and all related Attributes by ID.
Required Permissions
Attribute Management (Read/Write)
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 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 51©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
-
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.
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 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,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 52©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
-
ValueInt : int, // can be nullIsReadOnly: bool,},…]
},…]
Response Codes
200 – Request successful. Attributes in the response body.
For more information, please see "Common Response Codes" on page 14.
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
{AttributeID : int,AttributeTypeID : int,ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool,ChildAttributes :
[{AttributeID : int,
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 53©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
-
AttributeTypeID : int,ParentAttributeID : int,ShortName : string,LongName : string,Description : string,ValueInt : int, // can be nullIsReadOnly: bool,},…]
}
Response Codes
200 – Request successful. Attributes in the response body.
For more information, please see "Common Response Codes" on page 14.
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.
Request Body
Content-Type: application/json
{ParentAttributeID : int, // can be nullShortName : string,LongName : string,Description : string,ValueInt : int // can be null}
Response Body
Content-Type: application/json
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 54©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
-
{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
201 – Request successful. Attributes in the response body.
For more information, please see "Common Response Codes" on page 14.
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
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 55©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
-
Response Codes
200 – Request successful.
For more information, please see "Common Response Codes" on page 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 56©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
-
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.
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 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.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 57©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
-
For more information, please see "Common Response Codes" on page 14.
POST Assets/{assetID}/Attributes/{attributeID}
Purpose
Assigns an attribute to an Asset.
Required Permissions
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
Content-Type: application/json
{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 in the response body.
For more information, please see "Common Response Codes" on page 14.
DELETE Assets/{assetID}/Attributes
Purpose
Deletes all asset attributes by Asset 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 58©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
-
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 14.
DELETE Assets/{assetID}/Attributes/{attributeID}
Purpose
Deletes an asset attribute by Asset ID and Attribute ID.
Required Permissions
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
200 – Request successful.
For more information, please see "Common Response Codes" on page 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 59©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
-
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 14.
SALES: www.beyondtrust.com/contact SUPPORT: www.beyondtrust.com/support DOCUMENTATION: www.beyondtrust.com/docs 60©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
-
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.
Required Permissions
Asset Management (Read)
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 61©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
-
…]
Response Codes
201 – Request successful. Databases in the response body.
For more information, please see "Common Response Codes" on page 14.
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,In