User Groups

Quick Navigation

GET UserGroups

Returns a list of active and inactive User Groups.

User Accounts Management (Read)

None

Content-Type: application/json

[
    {
        GroupID : int, 
        Name : string,
        DistinguishedName : string,
        Description : string,
        GroupType : string, 
        AccountAttribute : string, 
        MembershipAttribute : string,
        IsActive : bool
    },
    …
]

200 – Request successful. User Group in the response body.

For more information, please see Common Response Codes.

GET UserGroups/{id}

Returns a User Group by ID.

User Accounts Management (Read)

id: ID of the User Group.

None

Content-Type: application/json

{
    GroupID : int, 
    Name : string,
    DistinguishedName : string,
    Description : string, 
    GroupType : string, 
    AccountAttribute : string, 
    MembershipAttribute : string,
    IsActive : bool
}

200 – Request successful. User Group in the response body.

For more information, please see Common Response Codes.

GET UserGroups?name={name}

Returns a User Group by name.

User Accounts Management (Read)

name: Name of the User Group.

None

Content-Type: application/json

{
    GroupID : int, 
    Name : string,
    DistinguishedName : string, 
    GroupType : string, 
    AccountAttribute : string, 
    MembershipAttribute : string,
    IsActive : bool
}

200 – Request successful. User Group in the response body.

For more information, please see Common Response Codes.

POST UserGroups

Creates a new User Group with Permissions, Smart Rule access, and optionally Application Registration IDs.

User Accounts Management (Read/Write)

Creating a User Group that has the Team Passwords Feature/Permission enabled requires the caller to be an Administrator.

The request body differs for the different group types available: BeyondInsight, ActiveDirectory, LdapDirectory.

BeyondInsight Group Type

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, … ]
}
  • 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

Content-Type: application/json

{
    groupType : string = "ActiveDirectory", 
    groupName : string,
    forestName : string, 
    domainName : string, 
    description : string, 
    bindUser : string, 
    bindPassword : string, 
    useSSL : bool,

    isActive : bool,
    Permissions : [ { PermissionID: int, 
    AccessLevelID: int }, ... ], 
    SmartRuleAccess : [ { SmartRuleID: int, AccessLevelID: int }, ... ], 
    ApplicationRegistrationIDs: [ int, … ]
}
  • 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.

For more information, please see Common Request Body Details.

LdapDirectory Group Type

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

Content-Type: application/json

{
    GroupID : int, Name : string,
    DistinguishedName : string,
    Description : string,
    GroupType : string, 
    AccountAttribute : string, 
    MembershipAttribute : string,
    IsActive : bool
}

201 – Request successful. User Group in the response body.

For more information, please see Common Response Codes.

DELETE UserGroups/{id}

Deletes a User Group by ID.

User Accounts Management (Read/Write)

Deleting a User Group that has the Team Passwords Feature/Permission enabled requires the caller to be an Administrator.

id: ID of the User Group.

None

None

200 – Request successful.

For more information, please see Common Response Codes.

DELETE UserGroups?name={name}

Deletes a User Group by name.

User Accounts Management (Read/Write)

Deleting a User Group that has the Team Passwords Feature/Permission enabled requires the caller to be an Administrator.

name: Name of the User Group.

None

None

200 – Request successful.

For more information, please see Common Response Codes.