User Groups

Quick Navigation

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.