Users

Quick Navigation

GET Users

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.

User Accounts Management (Read)

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

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

None

Content-Type: application/json

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

200 – Request successful. Users in the response body.

For more information, please see Common Response Codes.

GET UserGroups/{userGroupId}/Users

Returns a list of Users for the User Group referenced by ID.

User Accounts Management (Read)

userGroupId: ID of the User Group.

None

Content-Type: application/json

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

200 – Request successful. Users in the response body.

For more information, please see Common Response Codes.

GET Users/{id}

Returns a User by ID.

User Accounts Management (Read)

id: ID of the User.

None

Content-Type: application/json

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

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

POST Users

Creates a new User with no User Group associations.

User Accounts Management (Read/Write)

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
}
  • 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,
}
  • 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
}
  • 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).

Content-Type: application/json

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

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

POST Users/{id}/Quarantine

Quarantines the User referenced by ID.

Password Safe API Global Quarantine (Read/Write)

id: ID of the BeyondInsight User.

None

Content- Type: application/json

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

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

POST UserGroups/{userGroupId}/Users

Creates a User in a BeyondInsight-type User Group.

User Accounts Management (Read/Write)

userGroupId: ID of the User Group.

Content-Type: application/json

{
    UserName : string, 
    FirstName : string, 
    LastName : string, 
    EmailAddress : string, 
    Password : string
}
  • 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.

Content-Type: application/json

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

201 – Request successful. User in the response body.

For more information, please see Common Response Codes.

PUT Users/{id}

Updates a BeyondInsight User by ID.

Cannot update ActiveDirectory or LDAP users.

User Accounts Management (Read/Write)

id: ID of the BeyondInsight User.

Content-Type application/json

{
    UserName : string, 
    FirstName : string, 
    LastName : string, 
    EmailAddress : string, 
    Password: string
}
  • 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.

Content- Type: application/json

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

200 – Request successful. User in the response body.

For more information, please see Common Response Codes.

DELETE Users/{id}

Deletes a User by ID.

User Accounts Management (Read/Write)

id: ID of the User.

None

200 – Request successful.

For more information, please see Common Response Codes.