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,   
        LastLoginDate : DateTime,
        LastLoginAuthenticationType : string,
        LastLoginConfigurationName : string,
        LastLoginSAMLIDPURL : string,
        LastLoginSSOURL : string,
        IsQuarantined: bool
    },
    …
]

Application User Type:

ClientSecret has no value; it can only be retrieved via API by initial creation or recycling it. Please see Users.

{
    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
}

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.

For Active Directory, Azure AD, 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
    },
    …
]

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,
    LastLoginDate : DateTime,
    LastLoginAuthenticationType : string,
    LastLoginConfigurationName : string,
    LastLoginSAMLIDPURL : string,
    LastLoginSSOURL : string,
    IsQuarantined: bool
  }
]

Application User Type

ClientSecret has no value; it can only be retrieved via API by initial creation or recycling it. Please see Users.

{
    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
}

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.

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).

Application User Type

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

For more information, please see Common Request Body Details.

Response Body

Content-Type: application/json

[
  {
    UserID : int,
    UserName : string,
    DomainName : string,
    DistinguishedName : string,
    FirstName : string,
    LastName : string,
    EmailAddress : string,
    IsQuarantined: 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
}

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.

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

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.

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.

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
  }
]

Application User Type

ClientSecret has no value; it can only be retrieved via API by initial creation or recycling it. Please see Users.

{
    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
}

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).

  • 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.

For more information, please see Common Response Codes.