BeyondInsight APIs
The BeyondInsight APIs require a valid BeyondInsight license and are available to Password Safe-licensed installs.
This document specifies the Representational State Transfer (REST) compliant Application Programmer Interface (API) over HTTPS for BeyondInsight and Password Safe. It is a way to integrate a portion of the BeyondInsight and Password Safe functionality into your own applications.
Using the REST API makes it easier for users to build customized solutions for their specific needs while ensuring secure data transmission. The API provides a set of predefined operations, or endpoints, that can be accessed using HTTP Requests, including GET requests to retrieve data, POST requests to create new data, PUT requests to update existing data, and DELETE requests to remove data.
This resource is intended for readers with knowledge of HTTPS request and response processing, web development, and JSON notation.
Access levels
(i.e., None, Read, Read/Write)
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.
POST UserGroups/{userGroupId}/SmartRules/{smartRuleId}/AccessLevels
Purpose
Sets the Access Level for a User Group Smart Rule.
Required permissions
- User Accounts Management (Read/Write).
URL parameters
- userGroupId: ID of the user group.
- smartRuleId: ID of the Smart Rule.
Request body
Content-Type: application/json
{
AccessLevelID: int
}
Response body
None.
Response codes
- 200 - Request successful.
Note
For more information, see "Common Response Codes" on page 1.
Address groups
GET Organizations/{orgID}/AddressGroups
Purpose
List the address groups for a given organization.
Required permissions
- Current user has access to the organization.
- Asset Management (Read).
URL parameters
orgId: Organization ID.
Request body
None.
Response body
Content-Type: application/json
[
{
AddressGroupID: int,
Name: string,
OrganizationID: guid // can be null
}
]
Response codes
200 - Request successful.
GET AddressGroups
Purpose
List the address groups.
Required permissions
- Current user has access to the organization.
- Asset Management (Read).
URL parameters
None.
Request body
None.
Response body
Content-Type: application/json
[
{
AddressGroupID: int,
Name: string,
OrganizationID: guid // can be null
{
]
Response codes
200 - Request successful.
GET AddressGroups/{addressGroupId}/Addresses
Purpose
List the addresses for an address group.
Required permissions
- Current user has access to the organization.
- Asset Management (Read).
URL parameters
addressGroupId: Address Group ID.
Request body
None.
Response body
Content-Type: application/json
[
{
AddressID: int,
AddressGroupID: int,
Omit: boolean,
Type: int,
Value: string,
LastUpdatedDate: datetime
}
]
Response body details
- Type: The Address type
- 1: Single IP Address
- 2: IP Address Range
- 3: CIDR Notation
- 4: Named Host
- Omit: true to omit this entry, otherwise false.
Response codes
200 - Request successful.
POST AddressGroups/{id}/Addresses
Purpose
Create an address in an Address Book.
Required permissions
- Asset Management (Read/Write).
URL parameters
addressGroupId: Address Group ID.
Request body
{
Type: int,
Value: string,
Omit: bool
}
Request body details
- Max string length for Value is 225.
- Type: The Address type
- 1: Single IP Address
- 2: IP Address Range
- 3: CIDR Notation
- 4: Named Host
- Omit: true to omit this entry, otherwise false.
Response body
Content-Type: application/json
{
AddressID: int,
AddressGroupID: int,
Omit: bool,
Type: int,
Value: string,
LastUpdatedDate: datetime
}
Response body details
- Type: The Address type
- 1: Single IP Address
- 2: IP Address Range
- 3: CIDR Notation
- 4: Named Host
- Omit: true to omit this entry, otherwise false.
Response codes
201 - Request successful. Address in the response body.
DELETE AddressGroups/{addressGroupId}
Purpose
Delete the address group and all it's addresses.
Required permissions
- Current user has access to the organization.
- Asset Management (Read/Write).
URL parameters
addressGroupId: Address Group ID.
Request body
None.
Response body
None.
Response codes
200 - Request successful.
DELETE AddressGroups/{addressGroupId}/Addresses
Purpose
Delete the addresses within the address group.
Required permissions
- Current user has access to the organization.
- Asset Management (Read/Write).
URL parameters
addressGroupId: Address Group ID.
Request body
None.
Response body
None.
Response codes
200 - Request successful.
GET AddressGroups/?name={name}
Purpose
Returns the Address Group by name.
Required permissions
- Asset Management (Read).
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.
GET AddressGroups/{id}
Purpose
Returns the Address Group by ID.
Required permissions
- Asset Management (Read).
URL parameters
id: ID of the Address Group.
Request body
None.
Response body
Content-Type: application/json
{
AddressGroupID: int,
Name: string
}
Response codes
200 - Request successful. Address Group in the response body.
PUT AddressGroups/{id}
Purpose
Updates and Address Group by ID.
Required permissions
- Asset Management (Read/Write).
Request body
Content-Type: application/json
{
Name: string,
}
Request body details
Max string length for Name is 225.
Response body
Content-Type: application/json
{
AddressGroupID: int,
Name: string
}
Response codes
200 - Request successful. Address Group in the response body.
POST AddressGroups
Purpose
Creates an Address Book.
Required permissions
- Asset Management (Read/Write).
Request body
Content-Type: application/json
{
Name: string
}
Request body details
Max string length for Name is 225.
Response body
Content-Type: application/json
{
AddressGroupID: int,
Name: string
}
Response codes
201 - Request successful. Address Group in the response body.
GET Addresses/{id}
Purpose
Returns the Address by ID.
Required permissions
- 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: int,
Value: string,
LastUpdateDate: datetime
}
Response body details
- Type: The Address type
- 1: Single IP Address
- 2: IP Address Range
- 3: CIDR Notation
- 4: Named Host
- Omit: true to omit this entry, otherwise false.
Response codes
200 - Request successful. Address in the response body.
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.
PUT Addresses/{id}
Purpose
Updates and Address by ID.
Required permissions
- Asset Management (Read/Write).
Request body
Content-Type: application/json
{
Type: int,
Value: string,
Omit: bool
}
Request body details
- Max string length for Value is 225.
- Type: The Address type
- 1: Single IP Address
- 2: IP Address Range
- 3: CIDR Notation
- 4: Named Host
- Omit: true to omit this entry, otherwise false.
Response body
Content-Type: application/json
{
AddressD: int,
AddressGroupID: int,
Omit: bool,
Type: int,
Value: string,
LastUpdateDate: datetime
}
Response body details
- Type: The Address type
- 1: Single IP Address
- 2: IP Address Range
- 3: CIDR Notation
- 4: Named Host
- Omit: true to omit this entry, otherwise false.
Response codes
200 - Request successful. Address in the response body.
API registrations
GET ApiRegistrations
Purpose
Returns a list of all API registrations.
Required permissions
API Registration Management (Read).
Query parameters
...
Request body
None.
Response body
Content-Type: application/json
{
Id: int,
Name: string,
RegistrationType: string,
Active: bool,
Visible: bool,
MultiFactorAuthenticationEnforced: bool,
ClientCertificateRequired: bool,
UserPasswordRequired: bool,
VerifyPsrunSignature: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate: date
},
...
],
PSRUNRules:[
{
Id:int,
IPAddress: string,
MacAddress: string,
SystemName: string,
FQDN: string,
DomainName: string,
UserId: string,
RootVolumeId: string,
OSVersion: string,
CreatedDate: date
},
...
],
XForwardedForAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate: date
},
...
]
}
Response codes
200 – Request successful. API Registration in the response body.
GET ApiRegistrations/{id}
Purpose
Returns an API registration by ID.
Required permissions
API Registration Management (Read).
Query parameters
Id: ID of the API registration.
Request body
None.
Response body
Content-Type: application/json
{
Id: int,
Name: string,
RegistrationType: string,
Active: bool,
Visible: bool,
MultiFactorAuthenticationEnforced: bool,
ClientCertificateRequired: bool,
UserPasswordRequired: bool,
VerifyPsrunSignature: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate: date
},
...
],
PSRUNRules:[
{
Id:int,
IPAddress: string,
MacAddress: string,
SystemName: string,
FQDN: string,
DomainName: string,
UserId: string,
RootVolumeId: string,
OSVersion: string,
CreatedDate: date
},
...
],
XForwardedForAuthenticationRules: [
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate: date
},
...
]
}
Response codes
200 – Request successful. API Registration in the response body.
POST ApiRegistrations
Purpose
Creates an API registration.
Required permissions
API Registration Management (Read/Write).
Query parameters
...
Request body
The request body differs by RegistrationType.
Content-Type: application/json
ApiKeyPolicy
{
Id: int,
Name: string,
RegistrationType: string = “ApiKeyPolicy”,
Active: bool,
Visible: bool,
MultiFactorAuthenticationEnforced: bool,
ClientCertificateRequired: bool,
UserPasswordRequired: bool,
VerifyPsrunSignature: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
],
PSRUNRules:[
{
Id:int,
IPAddress: string,
MacAddress: string,
SystemName: string,
FQDN: string,
DomainName: string,
UserId: string,
RootVolumeId: string,
OSVersion: string,
},
...
],
XForwardedForAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
]
}
ApiAccessPolicy
{
Id: int,
Name: string,
RegistrationType: string = “ApiAccessPolicy”,
AccessTokenDuration: int = 60,
Active: bool,
Visible: bool,
ClientCertificateRequired: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
],
XForwardedForAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
]
}
Response body
Content-Type: application/json
{
Id: int,
Name: string,
RegistrationType: string,
AccessTokenDuration: int,
Active: bool,
Visible: bool,
MultiFactorAuthenticationEnforced: bool,
ClientCertificateRequired: bool,
UserPasswordRequired: bool,
VerifyPsrunSignature: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate; date
},
...
],
PSRUNRules:[
{
Id:int,
IPAddress: string,
MacAddress: string,
SystemName: string,
FQDN: string,
DomainName: string,
UserId: string,
RootVolumeId: string,
OSVersion: string,
CreatedDate; date
},
...
],
XForwardedForAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate; date
},
...
]
}
Response codes
200 – Request successful. API Registration in the response body.
PUT ApiRegistrations/{id}
Purpose
Updates an API registration by ID.
Required permissions
API Registration Management (Read/Write).
Query parameters
Id: ID of the API registration.
Request body
The request body differs by Registration Type.
Content-Type: application/json
ApiKeyPolicy
{
Id: int,
Name: string,
RegistrationType: string = “ApiKeyPolicy”,
Active: bool,
Visible: bool,
MultiFactorAuthenticationEnforced: bool,
ClientCertificateRequired: bool,
UserPasswordRequired: bool,
VerifyPsrunSignature: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
],
PSRUNRules:[
{
Id:int,
IPAddress: string,
MacAddress: string,
SystemName: string,
FQDN: string,
DomainName: string,
UserId: string,
RootVolumeId: string,
OSVersion: string,
},
...
],
XForwardedForAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
]
}
ApiAccessPolicy
{
Id: int,
Name: string,
RegistrationType: string = “ApiAccessPolicy”,
AccessTokenDuration: int = 60,
Active: bool,
Visible: bool,
ClientCertificateRequired: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
],
XForwardedForAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
},
...
]
}
Response body
Content-Type: application/json
{
Id: int,
Name: string,
RegistrationType: string,
AccessTokenDuration: int,
Active: bool,
Visible: bool,
MultiFactorAuthenticationEnforced: bool,
ClientCertificateRequired: bool,
UserPasswordRequired: bool,
VerifyPsrunSignature: bool,
IPAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate; date
},
...
],
PSRUNRules:[
{
Id:int,
IPAddress: string,
MacAddress: string,
SystemName: string,
FQDN: string,
DomainName: string,
UserId: string,
RootVolumeId: string,
OSVersion: string,
CreatedDate; date
},
...
],
XForwardedForAuthenticationRules:[
{
Id: int,
Type: string,
Value: string,
Description: string,
CreatedDate; date
},
...
]
}
Response codes
200 – Request successful. API Registration in the response body.
DELETE ApiRegistrations/{id}
Purpose
Deletes the API Registration for the ID provided.
Required permissions
API Registration Management (Read/Write).
Request body
None.
Response body
None.
Response codes
200 – Request successful.
POST ApiRegistrations/{id}/Rotate
Note
For API Key Policy only.
Purpose
Rotates the API key for an API Key policy API Registration
Required permissions
API Registration Management (Read/Write).
Query parameters
...
Request body
None.
Response body
Content-Type: application/json
string
Response codes
201 – Request successful. API key in the response body.
GET ApiRegistrations/{id}/Key
Note
For API Key Policy only.
Purpose
Retrieves the API key for an API Key policy API Registration.
Required permissions
API Registration Management (Read/Write).
Query parameters
...
Request body
None.
Response body
Content- Type: application/json
string
Response codes
200 – Request successful. API Key in the response body.
Assets
GET Assets/{id}
Purpose
Returns an asset by ID.
Required permissions
Asset Management (Read).
URL parameters
id: ID of the asset.
Request body
None.
Response body
Content-Type: application/json
{
WorkgroupID: int,
AssetID: int,
AssetName: string,
DnsName: string,
DomainName: string,
IPAddress: string,
MacAddress: string,
AssetType: string,
Description: 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.
Required permissions
Asset Management (Read).
URL parameters
workgroupID: ID of the Workgroup.
Query parameters (optional)
- limit: (default: 100000) Number of records to return.
- offset: (default: 0) Number of records to skip before returning records (can be used in conjunction only with limit).
Request body
None.
Response body (when limit is not given)
Content-Type: application/json
[
{
WorkgroupID: int,
AssetID: int,
AssetName: string,
DnsName: string,
DomainName: string,
IPAddress: string,
MacAddress: string,
AssetType: string,
OperatingSystem: string,
CreateDate: datetime,
LastUpdateDate: datetime
},
…
]
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.
GET Workgroups/{workgroupName}/Assets
Purpose
Returns a list of assets by Workgroup name.
Required permissions
Asset Management (Read).
URL parameters
workgroupName: Name of the Workgroup.
Query parameters (optional)
- limit: (default: 100000) Number of records to return.
- offset: (default: 0) Number of records to skip before returning 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,
MacAddress: string,
AssetType: string,
OperatingSystem: string,
CreateDate: datetime,
LastUpdateDate: datetime
},
…
]
}
Response codes
200 - Request successful. Assets in response body.
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,
AssetType: string,
OperatingSystem: string,
CreateDate: datetime,
LastUpdateDate: datetime
}
Response codes
200 - Request successful. Asset in response body.
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,
Description: string,
OperatingSystem: string
}
Request body details
- IPAddress: (required) Asset IP address. Max string length is 45.
- AssetName: (optional) Asset name. If not given, a padded IP address is used. Max string length is 128.
- DnsName: (optional) Asset DNS name. Max string length is 255.
- DomainName: (optional) Asset domain name. Max string length is 64.
- MacAddress: (optional) Asset MAC address. Max string length is 128.
- AssetType: (optional) Asset type. Max string length is 64.
- Description: (optional) Asset description. Only updated if version in the URL is 3.1 or greater. Max string length is 255.
- OperatingSystem: (optional) Asset operating system. Max string length is 255.
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.
POST Workgroups/{workgroupName}/Assets
Purpose
Creates a new asset in the Workgroup referenced by name.
Required permissions
Asset Management (Read/Write).
URL parameters
workgroupName: Name of the Workgroup.
Request body
Content-Type: application/json
{
IPAddress: string,
AssetName: string,
DnsName: string,
DomainName: string,
MacAddress: string,
AssetType: string,
Description: string,
OperatingSystem: string
}
Request body details
- IPAddress: (required) Asset IP address. Max string length is 45.
- AssetName: (optional) Asset name. If not given, a padded IP address is used. Max string length is 128.
- DnsName: (optional) Asset DNS name. Max string length is 255.
- DomainName: (optional) Asset domain name. Max string length is 64.
- MacAddress: (optional) Asset MAC address. Max string length is 128.
- AssetType: (optional) Asset type. Max string length is 64.
- Description: (optional) Asset description. Only updated if version in the URL is 3.1 or greater. Max string length is 255.
- OperatingSystem: (optional) Asset operating system. Max string length is 255.
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.
PUT Assets/{id}
Purpose
Updates an existing asset by ID.
Note
Call GET Assets/{id} (or equivalent) first to get the current state of the asset before calling PUT Assets/{id} to update it with new values.
Required permissions
Asset Management (Read/Write).
URL parameters
id: ID of the asset.
Request body
Content-Type: application/json
{
WorkgroupID: int,
AssetName: string,
DnsName: string,
DomainName: string,
IPAddress: string,
MacAddress: string,
AssetType: string,
Description: string,
OperatingSystem: string,
}
Request body details
- WorkgroupID: (required) ID of the Workgroup to which the asset belongs.
- AssetName: (required) Asset name.
- DnsName: (required) Asset DNS name.
- DomainName: (required) Asset domain name.
- IPAddress: (required) Asset IP address.
- MacAddress: (required) Asset MAC address. An empty value is accepted and clears any existing value.
- AssetType: (required) Asset type. An empty value is accepted and clears any existing value.
- Description: (optional) Asset description. Only updated if version in the URL is 3.1 or greater. Max string length is 255.
- OperatingSystem: (required) Asset operating system. An empty value is accepted and clears any existing value.
Response body
Content-Type: application/json
{
WorkgroupID: int,
AssetID: int,
AssetName: string,
DnsName: string,
DomainName: string,
IPAddress: string,
MacAddress: string,
AssetType: string,
OperatingSystem: string,
CreateDate: datetime,
LastUpdateDate: datetime
}
Response codes
200 - Request successful. Asset in response body.
POST Assets/Search
Purpose
Returns a list of assets that match the given search criteria.
Required permissions
Asset Management (Read).
Query parameters (optional)
- limit: (default: 100000) Number of records to return.
- offset: (default: 0) Number of records to skip before returning records (can only be used in conjunction with limit).
Request body
Content-Type: application/json
{
AssetName: string,
DnsName: string,
DomainName: string,
IPAddress: string,
MacAddress: string,
AssetType: string,
}
Request body details
At least one request body property should be provided; any property not provided is ignored. All search criteria is case insensitive and is an exact match (equality), except for IPAddress.
IPAddress can be a single IP address (10.0.0.1), a comma-delimited list of IPs (10.0.0.1,10.0.0.2,10.0.0.3), an IP range (10.0.0.1-10.0.0.25), or CIDR notation (10.0.0.0/24).
Response body (when limit is not given)
Content-Type: application/json
[
{
WorkgroupID: int,
AssetID: int,
AssetName: string,
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.
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.
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.
Response body
None.
Response codes
200 - Request successful.
Smart Rule Assets
GET SmartRules/{id}/Assets
Purpose
Returns a list of assets by Smart Rule ID.
Required permissions
Read access to the Smart Rule referenced by ID.
URL parameters
id: ID of the Smart Rule.
Query parameters (optional)
- limit: (default: 100000) Number of records to return.
- offset: (default: 0) Number of records to skip before returning records (can be used only in conjunction with limit).
Request body
None.
Response body (when limit is not given)
Content-Type: application/json
[
{
WorkgroupID: int,
AssetID: int,
AssetName: string,
DnsName: string,
DomainName: string,
IPAddress: string,
MacAddress: string,
AssetType: string,
OperatingSystem: string,
CreateDate: datetime,
LastUpdateDate: datetime
},
…
]
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.
Asset attributes
GET Assets/{assetID}/Attributes
Purpose
Returns a list of attributes by Asset ID.
Required permissions
Asset Management (Read), Attribute Management (Read).
URL parameters
assetID: ID of the asset.
Request body
None.
Response body
Content-Type: application/json
[
{
AttributeID : int, AttributeTypeID : int,
ParentAttributeID : int, // can be null
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool
},
…
]
Response codes
200 – Request successful. Attributes associated with the asset in the response body.
POST Assets/{assetID}/Attributes/{attributeID}
Purpose
Assigns an attribute to an asset.
Required permissions
Asset Management (Read/Write), Attribute Management (Read/Write).
URL parameters
- assetID: ID of the asset.
- attributeID: ID of the attribute Request Body.
Response body
Content-Type: application/json
{
AttributeID : int, AttributeTypeID : int,
ParentAttributeID : int, // can be null
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool,
}
Response codes
201 – Request successful. Attributes in the response body.
DELETE Assets/{assetID}/Attributes
Purpose
Deletes all asset attributes by asset ID.
Required permissions
Asset Management (Read/Write), Attribute Management (Read/Write).
URL parameters
assetID: ID of the asset.
Request body
None.
Response body
None.
Response codes
200 – Request successful.
DELETE Assets/{assetID}/Attributes/{attributeID}
Purpose
Deletes an asset attribute by asset ID and attribute ID.
Required permissions
- Asset Management (Read/Write).
- Attribute Management (Read/Write).
URL parameters
assetID: ID of the asset attributeID and ID of the attribute.
Request body
None.
Response body
None.
Response codes
200 – Request successful.
Attributes
GET AttributeTypes/{attributeTypeID}/Attributes
Purpose
Returns a list of attribute definitions by attribute type.
Required permissions
Attribute Management (Read).
URL parameters
attributeTypeID: ID of the attribute type.
Request body
None.
Response body
Content-Type: application/json
[
{
AttributeID : int,
AttributeTypeID : int,
ParentAttributeID : int, // can be null
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool,
ChildAttributes :
[
{
AttributeID : int,
AttributeTypeID : int,
ParentAttributeID : int,
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool,
},
…
]
},
…
]
Response codes
200 – Request successful. Attributes in the response body.
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 null
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool,
ChildAttributes :
[
{
AttributeID : int,
AttributeTypeID : int,
ParentAttributeID : int,
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool,
},
…
]
}
Response codes
200 – Request successful. Attributes in the response body.
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 null
ShortName : string,
LongName : string,
Description : string,
ValueInt : int // can be null
}
Request body details
Max string length for ShortName and LongName is 64. Max string length for Description is 255.
Response body
Content-Type: application/json
{
AttributeID : int,
AttributeTypeID : int,
ParentAttributeID : int, // can be null
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool,
ChildAttributes :
[
{
AttributeID : int,
AttributeTypeID : int,
ParentAttributeID : int,
ShortName : string,
LongName : string,
Description : string,
ValueInt : int, // can be null
IsReadOnly: bool,
},
…
]
}
Response codes
201 – Request successful. Attributes in the response body.
DELETE Attributes/{id}
Purpose
Deletes an attribute definition by ID.
Required permissions
Attribute Management (Read/Write).
URL parameters
id: ID of the attribute.
Request body
None.
Response body
None.
Response codes
200 – Request successful.
Attribute types
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.
GET AttributeTypes/{id}
Purpose
Returns an attribute type by ID.
Required permissions
Attribute Management (Read).
URL parameters
id: ID of the attribute type.
Request body
None.
Response body
Content-type: application/json
{
AttributeTypeID : int,
Name : string,
IsReadOnly: bool
}
Response codes
200 – Request successful. Attribute type in the response body.
POST AttributeTypes
Purpose
Creates a new attribute type.
Required permissions
Attribute Management (Read/Write).
Request body
Content-Type: application/json
{
Name : string
}
Request body details
Max string length for Name is 64.
Response body
Content-type: application/json
{
AttributeTypeID : int,
Name : string,
IsReadOnly: bool
}
Response codes
201 – Request successful. Attribute type in the response body.
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.
Databases
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
},
…
]
Response codes
201 – Request successful. Databases in the response body.
GET Databases/{id}
Purpose
Returns a database by ID.
Required permissions
Asset Management (Read).
URL parameters
id: ID of the database.
Request body
None.
Response body
Content-Type: application/json
{
AssetID:int,
DatabaseID : int,
PlatformID : int,
InstanceName : string,
IsDefaultInstance : bool,
Port : int,
Version : string
}
Response codes
201 – Request successful. Databases in the response body.
GET Assets/{id}/Databases
Purpose
Returns a list of databases for the given asset.
Required permissions
Asset Management (Read).
URL parameters
id: ID of the asset.
Request body
None.
Response body
Content-Type: application/json
[
{
AssetID: int,
DatabaseID : int,
PlatformID : int,
InstanceName : string,
IsDefaultInstance : bool,
Port : int,
Version : string,
Template:string
},
…
Response codes
201 – Request successful. Databases in the response body.
POST Assets/{id}/Databases
Purpose
Creates a new database in the asset referenced by ID.
Required permissions
Asset Management (Read/Write).
URL parameters
id: ID of the asset.
Request body
Content-Type: application/json
{
PlatformID : int,
InstanceName : string,
IsDefaultInstance : bool,
Port : int,
Version : string,
Template : string,
}
Request body details
- PlatformID: (required) ID of the platform
- InstanceName: Name of the database instance. Required when IsDefaultInstance is false. Max string length is 100.
- IsDefaultInstance: True if the database instance is the default instance, otherwise false.
Note
Only MS SQL Server and MySQL platforms support setting this value to true.
- Port: (required) The database port.
- Version: The database version. Max string value is 20.
- Template: The database connection template.
Response body
Content-Type: application/json
{
AssetID: int,
DatabaseID : int,
PlatformID : int,
InstanceName : string,
IsDefaultInstance : bool,
Port : int,
Version : string,
Template:string
}
Response codes
200 – Request successful. Databases in the response body.
PUT Databases/{id}
Purpose
Updates an existing database by ID.
Required permissions
Asset Management (Read/Write).
URL parameters
id: ID of the database.
Request body
Content-Type: application/json
{
PlatformID: int,
InstanceName: string,
IsDefaultInstance: bool,
Port: int,
Version: string,
Template: string
}
Request body details
- PlatformID: (required) ID of the platform.
- InstanceName: Name of the database instance. Required when IsDefaultInstance is false. Max string length is 100.
- IsDefaultInstance: True if the database instance is the default instance, otherwise false.
Note
Only MS SQL Server and MySQL platforms support setting this value to true.
- Port: The database port.
- Version: The database version. Max string length is 20.
- Template: The database connection template.
Response body
Content-Type: application/json
{
AssetID: int,
DatabaseID: int,
PlatformID: int,
InstanceName: string,
IsDefaultInstance: bool,Port: int,
Version: string,
Template: string
}
Response codes
200 – Request successful. Databases in the response body.
DELETE Databases/{id}
Purpose
Deletes a database by ID.
Required permissions
Asset Management (Read/Write).
URL parameters
id: ID of the database.
Request body
None.
Response body
None.
Response codes
200 – Request successful.
Deprecated
The content in this section of the guide has been deprecated and is compatible with earlier versions only.
Imports
[deprecated] POST Imports/QueueImportFile
Note
This API has been deprecated and is available for backwards compatibility only. Use POST Imports with Base64FileContents instead.
Purpose
Queues a Password Safe XML import using multi-part form-data content.
Required permissions
Scan Management (Read/Write).
Request body
Content-Type: multipart/form-data
{
Content-type: application/json
{
WorkgroupID: int,
FileName: string
}
application/octet-stream
{
<string-encoded byte array representing the file>
}
}
Request body details
- WorkgroupID: ID of the Workgroup to import the assets into.
- FileName: Filename (including extension) of the import file.
Response body
Content-Type: application/json
{
ImportID: int
}
Response codes
- 200 – Request successful. Import ID in the response body.
- 400 – The import file was not found in the body of the request, or a request body validation error has occurred.
Smart Rules
[deprecated] POST SmartRules/FilterSingleAccount
Note
This API has been deprecated and is available for backwards compatibility only. Use QuickRules instead.
Purpose
Specialized action for creating a Managed Account-type Smart Rule for filtering a single Managed Account by System Name and Account Name.
Required permissions
Smart Rule Management - Managed Account (Read/Write).
Request body
Content-type: application/json
{
AccountID: int,
Title: string
}
Request body details
- AccountID: (required) ID of the managed account you want to filter by parent System Name and Account Name.
- Title: (optional) The title/name of the new Smart Rule. If omitted, a unique title is auto-generated.
Response body
Content-Type: application/json
{
SmartRuleID: int,
OrganizationID : string, // can be null
Title: string,
Description: string,
Category: string,
Status: int,
LastProcessedDate: datetime,
IsReadOnly: bool,
RuleType: string
}
Response codes
201 – Request successful. Smart Rule in the response body.
User Groups
[deprecated] GET UserGroups/{name}
Note
This API has been deprecated and is available for backwards compatibility only. Use GET UserGroups?name={name} instead.
Purpose
Returns a user group by name.
Required permissions
User Accounts Management (Read).
URL parameters
name: Name of the user group.
Request body
None.
Response body
Content-Type: application/json
{
GroupID : int, Name : string,
DistinguishedName : string,
GroupType : string,
AccountAttribute : string,
MembershipAttribute : string,
IsActive : bool
}
Response codes
200 – Request successful. User group in the response body.
[deprecated] DELETE UserGroups/{name}
Note
This API has been deprecated and is available for backwards compatibility only. Use DELETE UserGroups?name={name} instead.
Purpose
Deletes a user group by name.
Required permissions
User Accounts Management (Read/Write).
URL parameters
name: Name of the user group.
Request body
None.
Response body
None.
Response Codes
200 – Request successful.
Workgroups
[deprecated] GET Workgroups/{name}
Note
This API has been deprecated and is available for backwards compatibility only. Use GET Workgroups?name={name} instead.
Purpose
Returns a Workgroup by name.
Required permissions
Current user has permission to the Workgroup Organization. Asset Management (Read) or Scan Management (Read/Write).
Query parameters
name: Name of the Workgroup.
Request body
None.
Response body
Content-Type: application/json
{
OrganizationID : string,
ID : int,
Name : string
}
Response codes
200 – Request successful. Workgroups in the response body.
Entitlements
GET Entitlements
Purpose
Returns user entitlements.
Required permissions
Analytics and Reporting (Read).
URL parameters
None.
Request body
None.
Response body
Content-Type: application/json
[
{
GroupID : int,
Name : string,
SmartRuleId : int,
DistinguishedName : string,
AccessLevel : string, // can be null
RoleId : int,
RoleName : string,
DedicatedAccountPermissionOverride : string, // can be null
DedicatedToAppUserID : int, // can be null
DedicatedToAppUserName : string, // can be null
IsAdministratorGroup : bool,
UserID : int,
UserName : string,
ManagedAccountId : int,
AccountName : string,
RationalizedSystemName : string,
ApplicationName : string,
AccessPolicyName : string
}
]
GET Entitlements?groupIDs={groupID1,groupID2,groupID3…}
Purpose
Returns user entitlements for the specified group IDs.
Required permissions
Analytics and Reporting (Read).
URL parameters
groupIDs: Comma separated list of group IDs
Request body
None.
Response body
Content-Type: application/json
[
{
GroupID : int,
Name : string,
SmartRuleId : int,
Title : string,
SmartRuleType : string,
AccessLevel : string, // can be null
RoleId : int,
RoleName : string,
DedicatedAccountPermissionOverride : string, // can be null
DedicatedToAppUserID : int, // can be null
DedicatedToAppUserName : string, // can be null
IsAdministratorGroup : bool,
UserID : int,
UserName : string,
ManagedAccountId : int,
AccountName : string,
RationalizedSystemName : string,
ApplicationName : string,
AccessPolicyName : string
}
]
EPM Policies
POST /{id}/epmapplications/add
Purpose
Edits a policy to add an application, and updates this policy in the BeyondInsight database. Touches the LastModifiedDate to indicate that a change is made. Updated policy is deployed to agents per the usual process in BeyondInsight.
Required permissions
EPM (Read/Write)
EPM Policy (Read/Write)
Query parameters (optional)
{id} is a Policy Guid
Request body
Content-Type: application/json
{
GroupName: string,
Name: string,
Path: string,
Publisher: string,
ChildrenInheritToken: boolean
}
Request body details
All fields are required.
Example request
{
"GroupName":"powershell - Add",
"Name":"notepad3.exe",
"Path":"C:\\Windows\\System32\\notepad2.exe",
"Publisher":"Microsoft2",
"ChildrenInheritToken":"false"
}
Response body
Content-Type: application/json
{
<empty>
}
Response codes
200 – OK, successful
400 – Invalid Policy ID
Imports
POST Imports
Purpose
Queues a third-party import.
Required permissions
Scan Management (Read/Write).
Request body
Content-Type: application/json
{
WorkgroupID: int,
ImportType: string,
Filter: string,
FileName: string,
FileContents: byte[],
Base64FileContents: string
}
Note
Provide either FileContents or Base64FileContents.
Request body details
-
WorkgroupID: ID of the Workgroup to import the assets into
-
ImportType: (case-senstitive, default: PASSWORDSAFE) Type of import being queued:
-
PASSWORDSAFE:Password Safe import file. Expected file extension: .xml.
-
RETINARTD: Retina© RTD file. Expected file extension: .rtd.
Note
Support for the following file types has been deprecated and will be removed from the product in a future version.
-
NESSUS: Nessus© import file. Expected file extension: .csv.
-
NESSUSSECCEN: NessusSecurityCenter© import file. Expected file extension: .csv.
-
NEXPOSE: Nexpose© import file. Expected file extension: .csv or .xml.
-
QUALYSGUARD: QualysGuard© file. Expected file extension: .csv or .xml.
-
METASPLOIT: METASPLOIT© import file. Expected file extension: .xml.
-
MCAFEEVM: McAfee Vulnerability Management© import file. Expected file extension: .csv.
-
TRIPWIRE: Tripwire© import file. Expected file extension: .csv.
-
-
Filter: (default: All Assets) Asset selection filter:
- All Assets: No filter, import all.
- Single IPv4 address (i.e. 10.0.0.1).
- IPv4 range (i.e. 10.0.0.1-10.0.0.5).
- CIDR (i.e. 10.0.0.0/24).
-
FileName: Filename (including extension) of the import file. One of the following is required:
- FileContents: The array containing the content of the import file.
- Base64FileContents: Base64 string containing the content of the import file.
Response body
Content-Type: application/json
{
ImportID: int
}
Response codes
200 – Request successful. Import ID in the response body.
Operating Systems
GET OperatingSystems
Purpose
Returns a list of operating systems.
Required permissions
Asset Management (Read).
Request body
None.
Response body
Content-Type: application/json
[
{
OperatingSystemID : int,
Name : string
},
…
]
Response codes
200 – Request successful. Operating systems in the response body.
Organizations
GET Organizations
Purpose
Returns a list of organizations to which the current user has permission.
Required permissions
Asset Management (Read).
Request body
None.
Response body
Content-Type: application/json
[
{
OrganizationID : string,
Name : string,
IsActive : bool
},
…
]
Response codes
200 – Request successful. Organizations in the response body.
GET Organizations/{id}
Purpose
Returns an organization by ID.
Required permissions
- Current user has permission to the organization.
- Asset Management (Read).
URL parameters
id: ID of the organization.
Request body
None.
Response body
Content-Type: application/json
{
OrganizationID : string,
Name : string,
IsActive : bool
}
Response codes
200 – Request successful. Organizations in the response body.
GET Organizations?name={name}
Purpose
Returns an organization by name.
Required permissions
- Current user has permission to the organization
- Asset Management (Read).
Query parameters
name: Name of the organization.
Request body
None.
Response body
Content-Type: application/json
{
OrganizationID : string,
Name : string,
IsActive : bool
}
Response codes
200 – Request successful. Organizations in the response body.
Permissions
(i.e., Asset Management, User Accounts Management, Scan Management, etc.)
GET Permissions
Purpose
Returns a list of permissions.
Required permissions
User Accounts Management (Read).
Request body
None.
Response body
Content-Type: application/json
[
{
PermissionID : int,
Name : string
},
…
]
Response codes
200 – Request successful. Permissions in the response body.
User group permissions
GET UserGroups/{userGroupID}/Permissions
Purpose
Gets all permissions for the user group referenced by ID.
Required permissions
User Accounts Management (Read).
URL parameters
userGroupId: ID of the user group.
Request body
None.
Response body
Content-Type: application/json
[
{
PermissionID : int,
AccessLevelID : int
},
…]
Response codes
200 – Request successful. Permissions in the response body.
POST UserGroups/{userGroupId}/Permissions
Purpose
Sets permissions for the user group referenced by ID.
Required permissions
User Accounts Management (Read/Write).
Note
- Adding the Secrets Safe feature/permission to a user group requires the caller to be an administrator.
- The access level for Secrets Safe cannot be changed to disabled if the group has associated secrets.
URL parameters
userGroupId: ID of the user group.
Request body
Content-Type: application/json
[
{
PermissionID : int,
AccessLevelID : int
},
…
]
Response body
None.
Response codes
204 – Request successful. No content in body.
DELETE UserGroups/{userGroupId}/Permissions
Purpose
Deletes all permissions for the user group referenced by ID.
Required permissions
User Accounts Management (Read/Write).
Note
- Removing the Secrets Safe feature/permission from a user group requires the caller to be an administrator.
- Permissions for a User Group that has the Secrets Safe feature enabled cannot be deleted if the group has associated secrets.
URL parameters
userGroupId: ID of the user group.
Request body
None.
Response body
None.
Response codes
200 – Request successful.
Smart Rules
GET SmartRules
Purpose
Returns a list of Smart Rules to which the current user has at least read access.
Query parameters
type: (optional, default: all) Type of Smart Rules to return (all, managed account, managed system, and asset).
Request body
None.
Response body
Content-Type: application/json
[
{
SmartRuleID: int,
OrganizationID : string, // can be null
Title: string,
Description: string,
Category: string,
Status: int,
LastProcessedDate: datetime,
IsReadOnly: bool,
RuleType: string
},
…
]
Response codes
200 – Request successful. Smart Rule in the response body.
GET SmartRules/{id}
Purpose
Returns a Smart Rule by ID.
Required permissions
Read access to the Smart Rule referenced by ID.
URL parameters
id: ID of the Smart Rule.
Request body
None.
Response body
Content-Type: application/json
{
SmartRuleID: int,
OrganizationID : string, // can be null
Title: string,
Description: string,
Category: string,
Status: int,
LastProcessedDate: datetime,
IsReadOnly: bool,
RuleType: string
}
Response codes
200 – Request successful. Smart Rule in the response body.
GET UserGroups/{id}/SmartRules/
Purpose
Returns a list of Smart Rules to which the given user group ID has at least read access.
Requirements
User Accounts Management (Read).
URL parameters
id: ID of the user group.
Query parameters
accessLevel: (optional, default: 1,3) User group Smart Rule access level - A single value or comma-delimited list of values:
- 0: None.
- 1: Read.
- 3: Read/Write.
Request body
None.
Response body
Content-Type: application/json
[{
SmartRuleID: int,
OrganizationID : string, // can be null
Title: string,
Description: string,
Category: string,
Status: int,
LastProcessedDate: datetime,
IsReadOnly: bool,
RuleType: string,
AccessLevelID: int,
}
,...
]
Response codes
200 – Request successful. Smart Rules with user group access level in the response body.
GET SmartRules?title={title}
Purpose
Returns a Smart Rule by title.
In a multi-tenant environment, assumes global organization.
Required permissions
Read access to the Smart Rule referenced by title.
Query parameters
title: Title of the Smart Rule.
Request body
None.
Response body
Content-Type: application/json
{
SmartRuleID: int,
OrganizationID : string, // can be null
Title: string,
Description: string,
Category: string,
Status: int,
LastProcessedDate: datetime,
IsReadOnly: bool,
RuleType: string
}
Response codes
200 – Request successful. Smart Rule in the response body.
GET Organizations/{orgID}/SmartRules?title={title}
Purpose
Returns a Smart Rule by organization ID and title. This is only valid in a multi-tenant environment.
Required ermissions
Read access to the Smart Rule referenced by organization and title.
URL parameters
orgID: ID of the organization.
Query parameters
title: Title of the Smart Rule.
Request body
None.