Users

Quick Navigation

GET Users

Purpose

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

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.

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

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,
        IsQuarantined: bool
    },
    …
]

Response Codes

200 – Request successful. Users in the response body.

For more information, please see Common Response Codes.

GET UserGroups/{userGroupId}/Users

Purpose

Returns a list of users 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

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

Response Codes

200 – Request successful. Users in the response body.

For more information, please see Common Response Codes.

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,
    IsQuarantined: bool
}

Response Codes

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

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, ActiveDirectory, LdapDirectory

BeyondInsight User Type

Content-Type: application/json

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

Request Body Details

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

ActiveDirectory User Type

Content-Type: application/json

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

Request Body Details

  • UserName: (required) Name of the Active Directory user. Max string length is 64.
  • DomainName: (required) The directory domain name. Max string length is 250.
  • 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.

For more information, please see Common Request Body Details.

LdapDirectory User Type

Content-Type: application/json

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

Request Body Details

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

Response Body

Content-Type: application/json

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

Response Codes

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

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
}

Response Codes

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

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
}

Response Codes

201 – Request successful. User in the response body.

For more information, please see Common Response Codes.

PUT Users/{id}

Purpose

Updates a BeyondInsight user by ID.

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.

Response Body

Content- Type: application/json

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

Response Codes

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

DELETE Users/{id}

Purpose

Deletes a user by ID.

Required Permissions

User Accounts Management (Read/Write).

URL Parameters

id: ID of the user.

Request Body

None.

Response Codes

200 – Request successful.

For more information, please see Common Response Codes.