User Groups
Quick Navigation
- GET UserGroups
- GET UserGroups/{id}
- GET UserGroups?name={name}
- POST UserGroups
- DELETE UserGroups/{id}
- DELETE UserGroups?name={name}
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.
For more information, please see Common Response Codes.
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.
For more information, please see Common Response Codes.
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.
For more information, please see Common Response Codes.
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).
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, 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.
For more information, please see Common Request Body Details.
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.
For more information, please see Common Request Body Details.
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.
For more information, please see Common Request Body Details.
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.
For more information, please see Common Response Codes.
DELETE UserGroups/{id}
Purpose
Deletes a user group by ID.
Required Permissions
User Accounts Management (Read/Write).
- 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.
For more information, please see Common Response Codes.
DELETE UserGroups?name={name}
Purpose
Deletes a user group by name.
Required Permissions
User Accounts Management (Read/Write).
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.
For more information, please see Common Response Codes.