Users
Quick Navigation
- GET Users
- GET UserGroups/{userGroupId}/Users
- GET Users/{id}
- POST Users
- POST Users/{id}/Quarantine
- POST UserGroups/{userGroupId}/Users
- PUT Users/{id}
- DELETE Users/{id}
- POST/{id}/Users/{id}/RecycleClientSecret
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.