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.

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.

POST SmartRules/FilterAssetAttribute

Purpose

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

Required permissions

Asset Management (Read/Write).

Request body

Content-Type: application/json

{
    AttributeIDs: [ int, …],
    Title: string,
    Category: string,
    Description: string,
    ProcessImmediately: bool
}

Request body details

• AttributeIDs: (required) A list of attribute IDs to filter by. All the attributes must be of the same attribute type.
• Title: (required) The title/name of the new Smart Rule. Must be unique across all Smart Rules. Max string length is 75.
• Category: (required) The category in which to place the Smart Rule. Max string length is 50.
• Description: (optional, default: ) The Smart Rule description.
• ProcessImmediately: (optional, default: true) True to process the Smart Rule immediately, otherwise false to defer processing to the background Smart Rule processor.

Response body

Content-Type: application/json

{
    SmartRuleID: int,
    OrganizationID : string, // can be null
    Title: string,
    Description: string,
    Category: string,
    Status: int,
    LastProcessedDate: datetime,
    IsReadOnly: bool
}

Response codes

201 - Request successful. Smart Rule in response body.

POST SmartRules/{id}/Process

Purpose

Process a Smart Rule by ID.

Required permissions

Read/Write access to the Smart Rule.

URL parameters

ID: ID of the Smart Rule.

Query parameters

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

Request body

None.

Response body

Content-Type: application/json

{
    SmartRuleID: int,
    OrganizationID : string, // can be null
    Title: string,
    Description: string,
    Category: string,
    Status: int,
    LastProcessedDate: datetime,
    IsReadOnly: bool,
    RuleType: string
}

Response codes

• 200 – Request successful. Smart Rule in the response body.
• 409 – Conflict: the Smart Rule is currently processing.

DELETE SmartRules/{id}

Purpose

Deletes a Smart Rule by ID.

Required permissions

Read/Write access to the Smart Rule referenced by ID

URL parameters

ID: ID of the Smart Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

DELETE SmartRules?title={title}

Purpose

Deletes a Smart Rule by title.

In a multi-tenant environment, assumes global organization.

Required permissions

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

Query parameters

title: Title of the Smart Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

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

Purpose

Deletes a Smart Rule by organization ID and title.

Only valid in a multi-tenant environment.

Required permissions

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

URL parameters

orgID: ID of the organization.

Query parameters

title: Title of the Smart Rule.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Subscription delivery (Cloud only)

GET Subscriptions/Delivery

Purpose

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

Required permissions

Analytics and Reporting (Read).

URL parameters

None.

Request body

None.

Response body

Content-Type: application/json

[
    {
        int[] 
    }
]

Response body details

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

Response codes

200 – Request successful. Ids in the response body.

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

Purpose

Returns the subscription delivery for the requested id.

Required permissions

Analytics and Reporting (Read).

URL parameters

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

Request body

None.

Response body

Content-Type: application/json

[
  {
    ReportDeliveryId : int, 
    ScheduleId : int,
    Filename : string,
    ApplicationType : string, 
    Snapshot : string, 
  }
]

Response body details

• ReportDeliveryId: The ID of this subscription delivery in the database.
• ScheduleId: Schedule ID of the subscription associated with this subscription delivery.
• ApplicationType: The MIME type string identifying the format of the file. Will be one of the following:
  • application/msword (Word)
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (Excel)
  • application/pdf (Pdf)
  • image/tiff (TIFF)
  • text/csv (CSV)
• Snapshot: A Base64 string representing the byte array of the subscription delivery file itself.

Response codes

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

User audits

GET UserAudits

Purpose

Returns a list of user audits.

Required permissions

User Audit Management (Read).

Query parameters (optional)

• username: User name.
• actiontype: Action type.
• section: Section.
• startdate: Start date.
• enddate: End date.
• limit: (default: 1000) Number of records to return.
• offset: (default: 0) Number of records to skip before returning records.

Request body

None.

Response body

Content-Type: application/json

{
    TotalCount : int,
    Data: [
    {
    AuditID : int,
    ActionType : string,
    Section : string,
    UserID : int,
    UserName : string,
    IPAddress : string,
    CreateDate : datetime
    },
    ...
    ]
}

Response codes

200 – Request successful. User Audits in response body.

Records sort

Records are sorted by CreateDate in descending order (latest entries are shown first)

GET UserAudits/{auditId:int}/UserAuditDetails

Purpose

Returns a list of user audit details.

Required permissions

User Audit Management (Read).

Query parameters

• auditid: Audit ID
• limit: (default: 1000) Number of records to return.
• offset: (default: 0) Number of records to skip before returning records.

Request body

None.

Response body

Content-Type: application/json

{
    TotalCount: int,
    Data: [
    {
    AuditDetailsID : int, 
    Name: string,
    OldValue : string,
    NewValue : string
    },
    ...
    ]
}

User group memberships

GET Users/{userID}/UserGroups

Purpose

Returns the user group memberships for an existing user.

Required permissions

User Accounts Management (Read).

URL parameters

userID: ID of the user.

Request body

None.

Response body

Content-Type: application/json

[
    {
        GroupID : int, 
        Name : string,
        DistinguishedName : string, 
        GroupType : string, 
        AccountAttribute : string, 
        MembershipAttribute : string,
        IsActive : bool
    },
    …
]

Response codes

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

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

Purpose

Adds an existing user to a user group.

Required permissions

User Accounts Management (Read/Write).

URL parameters

• userID: ID of the user.
• userGroupID: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

{
    GroupID : int, Name : string,
    DistinguishedName : string, 
    GroupType : string, 
    AccountAttribute : string, 
    MembershipAttribute : string,
    IsActive : bool
}

Response codes

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

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

Purpose

Removes a user from a user group.

Required permissions

User Accounts Management (Read/Write).

URL parameters

• userID: ID of the user.
• userGroupID: ID of the user group.

Request body

None.

Response codes

200 – Request successful.

User groups

GET UserGroups

Purpose

Returns a list of active and inactive user groups.

Required permissions

User Accounts Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        GroupID : int, 
        Name : string,
        DistinguishedName : string,
        Description : string,
        GroupType : string, 
        AccountAttribute : string,
        ApplicationRegistrationIDs : string,
        MembershipAttribute : string,
        IsActive : bool
    },
    …
]

Response codes

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

GET UserGroups/{id}

Purpose

Returns a user group by ID.

Required permissions

User Accounts Management (Read).

URL parameters

id: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

[
  {
    GroupID : int, 
    Name : string,
    DistinguishedName : string,
    Description : string, 
    GroupType : string, 
    AccountAttribute : string,
    ApplicationRegistrationIDs : string,
    MembershipAttribute : string,
    IsActive : bool
  }
]

Response codes

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

GET UserGroups?name={name}

Purpose

Returns a user group by name.

Required permissions

User Accounts Management (Read).

Query 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,
    ApplicationRegistrationIDs : string, 
    MembershipAttribute : string,
    IsActive : bool
  }
]

Response codes

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

POST UserGroups

Purpose

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

Required permissions

User Accounts Management (Read/Write).

ℹ️

Note

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

Request body

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

BeyondInsight group type

Request body

Content-Type: application/json

{
    groupType : string = "BeyondInsight",
    groupName : string,
    description : string,
    isActive : bool,
    Permissions : [ { PermissionID: int, AccessLevelID: int }, ... ],
    SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ],
    ApplicationRegistrationIDs: [ int, … ]
}

Request body details

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

EntraId group type

Request body

Content-Type: application/json

{
    groupType : string = "EntraId",
    description : string,
    groupName : string,
    ClientId : string,
    TenantId : string,
    ClientSecret : string,
    AzureInstance: string,
    isActive : bool,
    Permissions : [ { PermissionID: int, AccessLevelID: int }, ... ],
    SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ],
    ApplicationRegistrationIDs: [ int, … ]
}

Request body details

• groupName: (required) Name of the EntraId user group. Max string length is 200.
• description: (required) Description of the user group. Max string length is 255.
• ClientID: (required) uniquely identifies your EntraID app.
  • If not given, attempts to use existing credentials for the directory. If specifying an existing credential, you also need Credential Management – Read. If specifying a new credential, you also need Credential Management – Read/Write.
• TenantId: (required) TenantID of the account.
• ClientSecret: (required) Client credential.
• AzureInstance: (optional) can have values of “AzureUsGovernment”, “AzurePublic”, or null. If the AzureInstance value is not provided or if it’s null, the instance defaults to AzurePublic unless the credential already exists. At that point it will take on the value of the existing credential.

ActiveDirectory group type

Request body

Content-Type: application/json

{
    groupType : string = "ActiveDirectory", 
    groupName : string,
    forestName : string, 
    domainName : string, 
    description : string, 
    bindUser : string, 
    bindPassword : string, 
    useSSL : bool,
    isActive : bool,
    ExcludedFromGlobalSync : bool,
    OverrideGlobalSyncSettings : bool,
    Permissions : [ { PermissionID: int, 
    AccessLevelID: int }, ... ], 
    SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ], 
    ApplicationRegistrationIDs: [ int, … ]
  }

Request body details

• groupName: (required) Name of the Active Directory group. Max string length is 200.
• domainName: (required) The directory domain name. Max string length is 250.
• description: (required) Description of the user group. Max string length is 255.
• bindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory. If specifying an existing credential, you also need Credential Management – Read. If specifying a new credential, you also need Credential Management – Read/Write.
  • bindPassword: Password for directory binding (required if bindUser is given).
  • forestName: The directory forest name (required when bindUser is given). Max string length is 300.
• useSSL: (default: false) Flag indicating whether to use SSL.
• ExcludedFromGlobalSync: (default false) Flag indicating if the Active Directory group uses the global group synchronization settings.
• OverrideGlobalSyncSettings: (default false) Flag indicating if the Active Directory group overrides the global group synchronization settings.

LdapDirectory group type

Request body

Content-Type: application/json

{
    groupType : string = "LdapDirectory", 
    groupName : string, 
    groupDistinguishedName : string, 
    hostName : string,
    bindUser : string, 
    bindPassword : string, 
    port : int,
    useSSL : bool, 
    membershipAttribute : string,
    accountAttribute : string,

    isActive : bool,
    Permissions : [ { PermissionID: int, 
    AccessLevelID: int }, ... ], 
    SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ],
    ApplicationRegistrationIDs: [ int, … ]
}

Request body details

• groupName: (required) Name of the LDAP group. Max string length is 200.
• groupDistinguishedName: (required) Distinguished name of the LDAP group. Max string length is 500.
• hostName: (required) The directory server host name or IP. Max string length is 50.
• bindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory. If specifying an existing credential, you also need Credential Management – Read. If specifying a new credential, you also need Credential Management – Read/Write.
  • bindPassword: Password for directory binding (Note: required if bindUser is given).
  • port: Directory server port (valid range: 1 to 65535) (required if bindUser is given).
  • useSSL: (default: false) Flag indicating whether to use SSL (required if bindUser is given).
• membershipAttribute: (required) Directory group membership attribute. Max string length is 255.
• accountAttribute: (required) Directory account naming attribute. Max string length is 255.

Common request body details

• isActive: (default: true) True if the group should be created as active, otherwise false.
• Permissions: One or more permissions and access levels to set for the new user group.
• SmartRuleAccess: One or more Smart Rules and access levels to set for the new user group.
• ApplicationRegistrationIDs: Zero or more IDs representing the API application registrations to grant the new user group. If given, enables API for the user group.

Response body

Content-Type: application/json

[
  {
    GroupID : int, Name : string,
    DistinguishedName : string,
    Description : string,
    GroupType : string, 
    AccountAttribute : string, 
    MembershipAttribute : string,
    IsActive : bool
  }
]

Response codes

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

Deletes a user group by ID.

Required permissions

User Accounts Management (Read/Write).

ℹ️

Note

• Deleting a user group that has the Secrets Safe feature/permission enabled requires the caller to be an administrator.
• User Groups that have the Secrets Safe feature enabled cannot be deleted if the group has associated secrets.

URL parameters

id: ID of the user group.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

DELETE UserGroups?name={name}

Purpose

Deletes a user group by name.

Required permissions

User Accounts Management (Read/Write).

ℹ️

Note

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

Query parameters

name: Name of the user group.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Users

GET Users

Purpose

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

ℹ️

Note

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

Required permissions

User Accounts Management (Read).

Query parameters (optional)

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

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

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

ℹ️

Note

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

ℹ️

Note

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

Request body

None.

Response body

Content-Type: application/json

[
    {
        UserID : int,
        UserName : string,
        DomainName : string,
        DistinguishedName : string,
        FirstName : string,
        LastName : string,
        EmailAddress : string,   
        LastLoginDate : DateTime,
        LastLoginAuthenticationType : string,
        LastLoginConfigurationName : string,
        LastLoginSAMLIDPURL : string,
        LastLoginSSOURL : string,
        IsQuarantined: bool,
     IsActive : bool
    },
    …
]

Application user type:

ℹ️

Note

ClientSecret has no value; it can only be retrieved via API by initial creation or recycling it. See BeyondInsight APIs.

{
    ClientID: string,
    ClientSecret: string = null,
    AccessPolicyID: int,
    UserID: int,
    UserType: string = "Application",
    UserName: string,
    DomainName: string = null,
    DistinguishedName: string = null,
    FirstName: string = null,
    LastName: string = null,
    EmailAddress: string = null, 
    IsQuarantined: bool,
    IsActive : bool
}

Response codes

200 – Request successful. Users in the response body.

GET UserGroups/{userGroupId}/Users

Purpose

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

ℹ️

Note

For Active Directory, Entra ID, or LDAP user groups, calling this endpoint also triggers the membership synchronization between the directory and BeyondInsight for the group identified by userGroupId.

Required permissions

User Accounts Management (Read).

URL parameters

userGroupId: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

[
    {
        UserID : int,
        UserName : string,
        DomainName : string,
        DistinguishedName : string,
        FirstName : string,
        LastName : string,
        EmailAddress : string,
        LastLoginDate : DateTime,
        LastLoginAuthenticationType : string,
        LastLoginConfigurationName : string,
        LastLoginSAMLIDPURL : string, 
        LastLoginSSOURL : string,
        IsQuarantined: bool,
     IsActive : bool
    },
    …
]

Response codes

200 – Request successful. Users in the response body.

GET Users/{id}

Purpose

Returns a user by ID.

Required permissions

User Accounts Management (Read).

URL parameters

id: ID of the user.

Request body

None.

Response body

Content-Type: application/json

[
  {
    UserID : int,
    UserName : string,
    DomainName : string,
    DistinguishedName : string,
    FirstName : string,
    LastName : string,
    EmailAddress : string,
    LastLoginDate : DateTime,
    LastLoginAuthenticationType : string,
    LastLoginConfigurationName : string,
    LastLoginSAMLIDPURL : string,
    LastLoginSSOURL : string,
    IsQuarantined: bool,
    IsActive : bool
  }
]

Application user type

{
    ClientID: string,
    ClientSecret: string = null,
    AccessPolicyID: int,
    UserID: int,
    UserType: string = "Application",
    UserName: string,
    DomainName: string = null,
    DistinguishedName: string = null,
    FirstName: string = null,
    LastName: string = null,
    EmailAddress: string = null, 
    IsQuarantined: bool,
    IsActive : bool
}

Response codes

200 – Request successful. User in the response body.

POST Users

Purpose

Creates a new user with no user group associations.

Required permissions

User Accounts Management (Read/Write).

Request body

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

BeyondInsight user type

Request body

Content-Type: application/json

{
    UserType : string = "BeyondInsight",
    UserName : string,
    FirstName : string,
    LastName : string,
    EmailAddress : string,
    Password : string
}

Request body details

• UserName: (required) Username of the user account. Max string length is 64.
• FirstName: (required) First name of the user. Max string length is 64.
• LastName: (optional) Last name of the user. Max string length is 64.
• EmailAddress: (required must be a properly formatted address) - Email address for the user. Max string length is 255.
• Password: (required) The password they would use to login to BeyondInsight.

EntraId user type

Request body

Content-Type: application/json

{
    UserType : string = "EntraId",
    UserName : string,
    ClientId : string,
    TenantId : string,
    ClientSecret : string,
    AzureInstance : string, 
    UseSSL : bool
}

Request body details

• UserName: (required) Username of the user account. Max string length is 64.
• ClientId: (required) uniquely identifies your EntraID app.
  • If not given, attempts to use existing credentials for the directory. If specifying an existing credential, you also need Credential Management – Read. If specifying a new credential, you also need Credential Management – Read/Write.
• TenantId: (required) TenantID of the account.
• ClientSecret: (required) Client credential.
• AzureInstance: (optional) Can have values of “AzureUsGovernment”, “AzurePublic”, or null. If the AzureInstance value is not provided or if it’s null, the instance defaults to AzurePublic unless the credential already exists. At that point it will take on the value of the existing credential.

ActiveDirectory user type

Request body

Content-Type: application/json

{
    UserType : string = "ActiveDirectory", 
    UserName : string,
    ForestName : string, 
    DomainName : string, 
    BindUser : string, 
    BindPassword : string, 
    UseSSL : bool,
}

Request body details

• UserName: (required) Name of the Active Directory user. Max string length is 64.
• DomainName: (required) The directory domain name. Max string length is 250.
• BindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory.
  • BindPassword: Password for directory binding (required when BindUser is given).
  • ForestName: The directory forest name (required when BindUser is given). Max string length is 300.
• UseSSL: (default: false) Flag indicating whether to use SSL.

LdapDirectory user type

Request body

Content-Type: application/json

{
    UserType: string = "LdapDirectory",
    HostName: string,
    DistinguishedName: string,
    AccountNameAttribute: string,
    BindUser: string,
    BindPassword: string,
    Port: int,
    UseSSL: bool
}

Request body details

• HostName: (required) The directory server host name or IP.
• DistinguishedName: (required) The DistinguishedName of the user to create. Max string length is 255.
• AccountNameAttribute: (required) The LDAP attribute to use for creating the username.
• BindUser: Username for directory binding. If not given, attempts to use existing credentials for the directory.
  • BindPassword: Password for directory binding. (required if BindUser is given).
  • Port: The directory server port. (used when BindUser and BindPassword are given).
  • UseSSL: Flag indicating whether to use SSL (used when BindUser and BindPassword are given).

Application user type

{
    UserType: string = "Application",
    UserName: string,
    AccessPolicyID: int
}

Response body

Content-Type: application/json

[
  {
    UserID : int,
    UserName : string,
    DomainName : string,
    DistinguishedName : string,
    FirstName : string,
    LastName : string,
    EmailAddress : string,
    IsQuarantined: bool,
    IsActive : bool
  }
]

Application user type

{
    ClientID: string,
    ClientSecret: string,
    AccessPolicyID: int,
    UserID: int,
    UserType: string = "Application",
    UserName: string,
    DomainName: string = null,
    DistinguishedName: string = null,
    FirstName: string = null,
    LastName: string = null,
    EmailAddress: string = null, 
    IsQuarantined: bool,
    IsActive : bool
}

Response codes

200 – Request successful. User in the response body.

POST Users/{id}/Quarantine

Purpose

Quarantines the user referenced by ID.

Required permissions

Password Safe API Global Quarantine (Read/Write).

URL parameters

id: ID of the BeyondInsight user.

Request body

None.

Response body

Content- Type: application/json

[
  {
    UserID : int,
    UserName : string,
    DomainName : string,
    DistinguishedName : string,
    FirstName : string,
    LastName : string,
    EmailAddress : string,
    IsQuarantined: bool,
    IsActive : bool
  }
]

Response codes

200 – Request successful. User in the response body.

POST UserGroups/{userGroupId}/Users

Purpose

Creates a user in a BeyondInsight-type user group.

Required permissions

User Accounts Management (Read/Write).

URL parameters

userGroupId: ID of the user group.

Request body

Content-Type: application/json

{
    UserName : string, 
    FirstName : string, 
    LastName : string, 
    EmailAddress : string, 
    Password : string
}

Request body details

• UserName: (required) Username of the user account. Max string length is 64.
• FirstName: (required) First name of the user. Max string length is 64.
• LastName: (optional) Last name of the user. Max string length is 64.
• EmailAddress: (required and must be a properly formatted address) Email address for the user. Max string length is 255.
• Password: (required) The password they would use to login to BeyondInsight.

Response body

Content-Type: application/json

[
  {
    UserID : int,
    UserName : string,
    DomainName : string,
    DistinguishedName : string,
    FirstName : string,
    LastName : string,
    EmailAddress : string,
    IsQuarantined: bool,
    IsActive : bool
  }
]

Response codes

201 – Request successful. User in the response body.

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

ℹ️

Note

For application user type only.

Purpose

Recycles the client secret for an application user.

Required permissions

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

Request body

None.

Response body

Content- Type: application/json

string

Response codes

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

PUT Users/{id}

Purpose

Updates a BeyondInsight user by ID.

ℹ️

Note

Cannot update ActiveDirectory or LDAP users.

Required permissions

User Accounts Management (Read/Write).

URL parameters

id: ID of the BeyondInsight user.

Request body

Content-Type application/json

{
    UserName : string, 
    FirstName : string, 
    LastName : string, 
    EmailAddress : string, 
    Password: string
}

Request body details

• UserName: (required) Username of the user account.
• FirstName: (required) First name of the user.
• LastName: (optional) Last name of the user.
• EmailAddress: (required and must be a properly formatted address) Email address for the user.
• Password: (optional) The password they would use to log in to BeyondInsight. If given, replaces the current password.

Application user type

{
    UserName: string,
    AccessPolicyID: int
}

Response body

Content- Type: application/json

[
  {
    UserID : int,
    UserName : string,
    DomainName : string,
    DistinguishedName : string,
    FirstName : string,
    LastName : string,
    EmailAddress : string,
    IsQuarantined: bool,
    IsActive : bool
  }
]

Application user type

{
    ClientID: string,
    ClientSecret: string = null,
    AccessPolicyID: int,
    UserID: int,
    UserType: string = "Application",
    UserName: string,
    DomainName: string = null,
    DistinguishedName: string = null,
    FirstName: string = null,
    LastName: string = null,
    EmailAddress: string = null, 
    IsQuarantined: bool,
    IsActive : bool
}

Response codes

200 – Request successful. User in the response body.

DELETE Users/{id}

Purpose

Deletes a user by ID.

Required permissions

User Accounts Management (Read/Write).

ℹ️

Note

• Users that have the Secrets Safe feature enabled cannot be deleted if that user is the only owner of at least one secret.
• If the user is not the sole owner of any secrets, but is one of multiple owners of a secret, then no error will be presented and the user can be deleted successfully. They will also be removed from the secrets they are part owners to.

URL parameters

id: ID of the user.

Request body

None.

Response codes

200 – Request successful.

Workgroups

GET Workgroups

Purpose

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

Request body

None.

Response body

Content-Type: application/json

[
    {
        OrganizationID : string, ID : int,
        Name : string
    },
    …
]

Response codes

200 – Request successful. Workgroups in the response body.

GET Workgroups/{id}

Purpose

Returns a Workgroup by ID.

Required permissions

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

Query parameters

id: ID of the Workgroup.

Request body

None.

Response body

Content-Type: application/json

{
    OrganizationID : string,
    ID : int,
    Name : string
}

Response codes

200 – Request successful. Workgroups in the response body.

GET Workgroups?name={name}

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.

POST Workgroups

Purpose

Creates a Workgroup.

Required permissions

Asset Management (Read/Write).

Request body

Content-Type: application/json

{
    OrganizationID: string,
    Name : string
}

Request body details

• Organization ID: (optional) The ID of the organization in which to place the new Workgroup. If empty, the Workgroup is placed in the default organization.
• Name: The name of the Workgroup. Max string length is 256.

Response body

Content-Type: application/json

{
    OrganizationID : string,
    ID : int,
    Name : string
}

Response codes

201 – Request successful. Workgroups in the response body.