Group Management

API endpoints for group management operations

Create a New Group

post

This endpoint allows customers to create new user groups for organizing and managing access to resources. Groups can represent teams, departments, or any logical grouping of users in your organization. By assigning permissions to groups rather than individual users, you can simplify and streamline access control.

Use Cases

• Team Setup: Create groups for teams, departments, or project-specific purposes.

• Streamlined Access Management: Use groups to manage access to pipelines, tools, and dashboards.

• Simplify Onboarding: Add users to groups during creation for immediate access to resources.

• RBAC Implementation: Align groups with roles and responsibilities for consistent permission management.

---

Required Access

• API Scope: api

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Group Name Validation:

  • Ensures the name meets formatting rules (e.g., lowercase, starts with a letter).

  • Validates uniqueness within the organization.

• Optional Member Addition:

  • Adds members via user IDs (preferred) or email addresses.

  • Resolves user details based on identifiers provided.

  • Rejects invalid or mixed identifiers.

• Response Generation:

  • Confirms group creation.

  • Optionally confirms membership updates if members were added.

---

Important Notes!

• Group Name Rules:

  • Must be lowercase.

  • Maximum length of 25 characters.

  • Must begin with a letter.

  • Can contain letters, numbers, dashes (-), and underscores (_).

  • Must be unique within the organization.

• Identifier Consistency: Provide either groupMemberUserIds OR groupMemberEmailAddresses, not both.

• Member Details:

  • User IDs are preferred.

  • Email addresses are a fallback if user IDs are unavailable.

• Invalid Identifiers: Any invalid user IDs or email addresses will result in an error.

• Examples:

  Valid Group Names	Invalid Group Names
  developers-team	123group (starts with a number)
  qa_testers	Dev-Team (contains uppercase)
  project123-admins	my@group (contains special character)

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Body

application/json

groupNamestringRequired

Name of the group (must follow group name rules described above).

Example: developers-team

groupMemberUserIdsstring[]Optional

List of user IDs to add as group members (preferred method). Do not provide this if using groupMemberEmailAddresses.

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

groupMemberEmailAddressesstring · email[]Optional

List of email addresses of group members to add (alternative method). Do not provide this if using groupMemberUserIds.

Example: ["[email protected]","[email protected]"]

Responses

200

Group created successfully.

application/json

messagestringOptionalExample: Group creation complete

400

Bad request (invalid input).

application/json

409

Group already exists.

application/json

500

Internal server error.

application/json

post

/api/v2/usermanagement/group

HTTPcURLJavaScriptPython

POST /api/v2/usermanagement/group HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "groupName": "developers-team",
  "groupMemberUserIds": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

Create group with user IDs (preferred)Create group with email addresses

{
  "message": "Group creation complete",
  "data": {
    "groupCreateResult": "Group created successfully",
    "groupMembershipUpdateResult": "Group membership updated successfully"
  }
}

Get a Specific Group

get

This endpoint retrieves detailed information about a specific group by its name. The response includes critical group's properties such as type, owner, sync status, and member count.

Use Cases

• Retrieve Group Details for Access Management: Fetch detailed information about a group to manage user permissions and access control within your application.

• Verify Group Existence Before Operations: Check if a group exists before performing actions like adding or removing members to prevent errors.

• Display Group Information in User Interfaces: Display group details in administrative dashboards or user interfaces for better visibility and management.

• Audit and Compliance Checks: Retrieve group information to ensure configurations comply with organizational policies and standards.

• Monitor Group Membership Changes: Keep track of group properties and membership counts for monitoring or notification purposes.

---

Required Access

• API Scopes: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User, Security Manager, Auditor

---

Process Details

• Group Validation: Validates the groupName parameter to ensure it adheres to the required rules.

• Group Existence Check: Verifies if the group exists within the organization's domain.

• Group Details Retrieval:

  • Fetches the group's details if the group is found.

  • Calculates the memberCount by determining the number of members in the group.

  • Removes sensitive properties (dn, domain, members) from the response to maintain security.

• Response Generation: Returns the sanitized group information, including the memberCount and other non-sensitive details.

---

Important Notes!

• Case Sensitivity: The groupName is case-sensitive and must match exactly.

• Response Data: Certain internal properties are omitted from the response for security reasons.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

groupNamestringRequired

The name of the group to retrieve (case-sensitive, must match exactly). Must meet the group name validation rules.

Example: developers-team

Responses

200

Successfully retrieved group information.

application/json

namestringOptional

Name of the group.

Example: developers-team

groupTypestringOptional

Type of the group (usually "user").

Example: user

ownerEmailstringOptional

Email address of the group owner.

Example: [email protected]

isSyncbooleanOptional

Indicates whether the group is synced with external systems.

Example: false

memberCountintegerOptional

Number of members in the group.

Example: 2

400

Bad Request - Invalid group name provided.

application/json

404

Group not found.

application/json

500

Internal server error.

application/json

get

/api/v2/usermanagement/group/{groupName}

HTTPcURLJavaScriptPython

GET /api/v2/usermanagement/group/{groupName} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "developers-team",
  "groupType": "user",
  "ownerEmail": "[email protected]",
  "isSync": false,
  "memberCount": 2
}

Delete a Specific Group

delete

This endpoint permanently deletes a group by its name. This operation is irreversible, and the group cannot be recovered once deleted. Use this endpoint to manage and clean up organizational groups effectively.

Use Cases

• Group Management: Remove obsolete or unused groups from the system.

• Access Control: Delete groups no longer relevant to streamline organizational roles and permissions.

• Compliance: Ensure group structures align with updated organizational policies.

---

Required Access

• API Scopes: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Group Validation:

  • Validates the groupName parameter to ensure it follows the required format and rules.

  • Rejects invalid or missing groupName parameters with appropriate error responses.

• Group Deletion:

  • Deletes the specified group if it exists.

  • Logs the deletion operation for auditing and troubleshooting purposes.

• Response Handling:

  • Confirms successful deletion with a confirmation message.

  • Returns error messages if the group does not exist or if any other issue occurs.

---

Important Notes!

• Irreversible Action: Once deleted, the group cannot be recovered.

• Case Sensitivity: The groupName parameter is case-sensitive and must match the group's exact name.

• Validation: The groupName must adhere to the required naming conventions.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

groupNamestringRequired

The name of the group to delete (case-sensitive, must match exactly).

Example: developers-team

Responses

200

Group deleted successfully.

application/json

messagestringOptional

Confirmation message with deletion status.

Example: Group deletion completed: true

400

Bad Request - Invalid group name or validation error.

application/json

404

Group not found.

application/json

422

Unprocessable Entity - Missing required parameters.

application/json

500

Internal server error.

application/json

delete

/api/v2/usermanagement/group/{groupName}

HTTPcURLJavaScriptPython

DELETE /api/v2/usermanagement/group/{groupName} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Group deletion completed: true"
}

Get All Groups or Filter by Name/ID

get

This endpoint fetches a comprehensive list of all groups within the organization. Optionally, the results can be filtered using a search term or specific group IDs (names). It supports flexible filtering and is designed to provide relevant group information for administrative and organizational tasks.

Use Cases

• Comprehensive Group Retrieval: Get a complete list of all groups in your organization.

• Filtered Results: Use search terms or specific group IDs to narrow down results based on your requirements.

• Administrative Dashboards: Populate admin interfaces with group details for management and monitoring.

• Auditing and Compliance: Ensure proper group configuration and compliance with organizational policies.

---

Required Access

• API Scopes: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User, Security Manager, Auditor

---

Process Details

• Query Parameter Handling:

  • search: Filters groups based on case-insensitive matches in their names.

  • id: Retrieves groups that match the provided case-insensitive group IDs (names).

• Data Sanitization: Cleans query inputs to ensure valid and safe processing.

• Filtering Logic:

  • Applies the id filter first, if provided.

  • Applies the search filter only if id is not provided.

• Response Generation: Returns sanitized group details with additional metadata like memberCount for each group.

---

Important Notes!

• Filter Priority: If both id and search are provided, the id parameter takes precedence.

• Sanitization: Query parameters are sanitized to ensure safe processing and prevent potential security risks.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Query parameters

searchstringOptional

Optional filter to search for groups by name (case-insensitive). Matches any part of the group name. Note: This parameter is ignored if the id parameter is provided.

Example: dev

idstringOptional

Comma-separated list of group IDs (names) to retrieve specific groups. Example: id=My Group Name, Other Group Name Note: Group names are case-insensitive for matching.

Responses

200

Successfully retrieved groups.

application/json

namestringOptional

Name of the group.

Example: developers-team

groupTypestringOptional

Type of the group.

Example: user

ownerEmailstringOptional

Email address of the group owner.

Example: [email protected]

isSyncbooleanOptional

Indicates whether the group is synced with external systems.

Example: false

memberCountintegerOptional

Number of members in the group.

Example: 5

500

Internal Server Error.

application/json

get

/api/v2/usermanagement/groups

HTTPcURLJavaScriptPython

GET /api/v2/usermanagement/groups HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "name": "developers-team",
    "groupType": "user",
    "ownerEmail": "[email protected]",
    "isSync": false,
    "memberCount": 5
  },
  {
    "name": "qa-team",
    "groupType": "user",
    "ownerEmail": "[email protected]",
    "isSync": false,
    "memberCount": 3
  }
]

Get Memberships for a Specific Group

get

This endpoint fetches a list of all members for a specified group. For each member, this endpoint returns either:

• The email address (if detailed user data is not available).

• Complete user details, including personal and organizational attributes, if available.

Use Cases

• Group Management: Retrieve detailed group membership for administrative tasks like auditing and user management.

• Access Control Validation: Ensure the correct members are part of a group by reviewing the full list of users.

• User Directory Integration: Populate group memberships in user-facing dashboards or other systems.

---

Required Access

• API Scopes: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Group Name Validation:

  • Validates the groupName parameter to ensure it meets the required format and matches the group name exactly (case-sensitive).

• Membership Retrieval:

  • Retrieves email addresses of group members.

  • If detailed user data is available, fetches comprehensive user information for each member.

• Response Composition:

  • Combines email-only and detailed user objects into a single response.

---

Important Notes!

• Case Sensitivity: The groupName parameter is case-sensitive and must match exactly.

• Partial Data: If user details are not available, only the email address is returned for each member.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

groupNamestringRequired

The name of the group to get memberships for (case-sensitive).

Example: developers-team

Responses

200

Successfully retrieved group memberships.

application/json

Array of group members, each represented as either a string (email address) or a complete user object.

string · emailOptional

Email address only (when user details are not available).

Example: [email protected]

or

400

Bad request or validation error.

application/json

404

Group not found.

application/json

500

Internal server error.

application/json

get

/api/v2/usermanagement/group/{groupName}/memberships

HTTPcURLJavaScriptPython

GET /api/v2/usermanagement/group/{groupName}/memberships HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  "[email protected]"
]

Replace All Members in a Specific Group

post

This endpoint replaces all existing members in a specified group with a new list of users provided in the request body. By overwriting current group membership, administrators can ensure that only the appropriate users are part of the group.

Use Cases

• Update Group Membership: Replace the members of a group with a new set of users based on changing organizational needs.

• Bulk User Management: Efficiently manage group membership by replacing the entire list of members in a single operation.

• Ensure Access Accuracy: Remove users who no longer need access and add those who require it.

---

Required Access

• API Scope: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Group Validation: Validates the groupName to ensure it meets naming rules.

• Member Validation:

  • Confirms that the members array is provided and properly formatted.

  • Ensures all identifiers are either valid email addresses or user IDs.

  • Checks that identifiers are not mixed types (all emails or all user IDs).

  • Removes duplicate identifiers.

• User Verification:

  • Validates that each provided identifier corresponds to an existing user in the system.

  • Flags and skips invalid users or identifiers.

• Membership Update:

  • Retrieves current group members.

  • Replaces current members with the provided list.

  • Removes users not included in the new list and adds new members.

• Response Generation:

  • Returns a success message with details of the replaced members.

---

Important Notes!

• Case Sensitivity: The groupName is case-sensitive and must match exactly.

• Identifier Consistency: Provide either all email addresses OR all user IDs, not a mix of both.

• Valid Formats: Identifiers must follow these rules:

  • Email Addresses: Must be in a valid email format.

  • User IDs: Must follow a valid database ID format.

• Empty Array: Sending an empty array removes all members from the group.

• Atomic Operation: If any validation fails, no changes are made to the group.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

groupNamestringRequired

The name of the group to replace members in (case-sensitive).

Example: developers-team

Bodyone of[]

application/json

List of identifiers (either all email addresses or all user IDs) that will become the new group members. Send an empty array to remove all members.

string · emailOptional

Valid email address.

or

string · userIdOptional

Valid user ID.

Responses

200

Members replaced successfully.

application/json

messagestringOptional

Success message.

Example: Group membership replacement completed successfully.

resultstringOptional

Detailed result of the operation.

Example: Members replaced successfully.

replacedMembersstring[]Optional

List of identifiers that were successfully added.

Example: ["[email protected]","[email protected]"]

400

Bad request (invalid input).

application/json

500

Internal server error.

application/json

post

/api/v2/usermanagement/group/{groupName}/members

HTTPcURLJavaScriptPython

POST /api/v2/usermanagement/group/{groupName}/members HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

[
  "[email protected]",
  "[email protected]"
]

Replace with new members using email addresses.Replace with new members using user IDs.Remove all members.

{
  "message": "Group membership replacement completed successfully.",
  "result": "Members replaced successfully.",
  "replacedMembers": [
    "[email protected]",
    "[email protected]"
  ]
}

Remove Members from a Specific Group

delete

This endpoint removes specified members from an existing group using either their email addresses or user IDs. This operation allows you to manage group memberships by explicitly removing users from a group, effectively revoking their access to resources associated with that group.

Use Cases:

• Revoke Access to Resources: Remove users from a group to revoke their access to pipelines, tools, or dashboards that rely on group-based permissions.

• Enforce Security Policies: Remove users who no longer require access to certain sensitive or restricted areas of the platform.

• Streamline User Offboarding: As part of a user offboarding process, remove departing employees or contractors from all relevant groups.

• Respond to Role Changes: Update group memberships to reflect changes in user responsibilities, such as transitioning from an active contributor to a read-only observer.

• Clean Up Group Memberships: Remove inactive or outdated user accounts from groups to ensure only relevant users retain access.

---

Required Access:

• API Scope: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details:

• Group Validation: Validates the groupName to ensure it meets naming rules.

• Group Existence Check: Verifies that the group exists.

• Member Validation:

  • Confirms that the members array is provided and properly formatted.

  • Ensures all identifiers are either valid email addresses or unique database identifiers.

  • Checks that identifiers are not mixed types (all emails or all user IDs).

  • Removes duplicate identifiers.

• User Existence Verification: Checks that all provided identifiers correspond to valid users.

• Group Membership Update:

  • Retrieves current members of the group.

  • Removes specified members from the group.

  • Members not in the group are skipped.

• Response Generation: Returns a success message with the list of members that were removed.

---

Important Notes!

• Case Sensitivity: The groupName is case-sensitive and must match exactly.

• Identifier Type Consistency: Provide either all email addresses or all user IDs, not a mix of both.

• Valid Formats: Identifiers must follow these rules:

  • Email Addresses: Must be in a valid email format.

  • User IDs: Must be valid valid unique database IDs.

• Duplicate Handling: Duplicate identifiers in the request are automatically removed.

• Skipped Members: Members not in the group are skipped without causing an error.

• Atomic Operation: If any validation fails, no changes are made to the group.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

groupNamestringRequired

The name of the group to remove members from (case-sensitive)

Example: developers-team

Bodyone of[]

application/json

List of identifiers (either all email addresses or all userIds) of members to remove

string · emailOptional

Email address of a user

or

string · databaseIdOptional

Unique database ID of a user

Responses

200

Members removed successfully

application/json

messagestringOptional

Success message

Example: Group membership update completed successfully

resultstringOptional

Detailed result of the operation

Example: Members removed successfully

removedMembersstring[]Optional

List of identifiers that were successfully removed

Example: ["[email protected]","[email protected]"]

400

Bad request (invalid input)

application/json

404

Group not found

application/json

500

Internal server error

application/json

delete

/api/v2/usermanagement/group/{groupName}/members

HTTPcURLJavaScriptPython

DELETE /api/v2/usermanagement/group/{groupName}/members HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

[
  "[email protected]",
  "[email protected]"
]

Remove members using email addressesRemove members using user IDs

{
  "message": "Group membership update completed successfully",
  "result": "Members removed successfully",
  "removedMembers": [
    "[email protected]",
    "[email protected]"
  ]
}

Add Members to a Specific Group

patch

This endpoint allows administrators to add new members to an existing group by specifying their email addresses or user IDs. Unlike replacing group membership entirely, this operation appends new members to the group while keeping the current members intact. Sending an empty array will, however, remove all existing members, making it versatile for reconfiguring group memberships.

Use Cases

• Manage User Access to Resources: Assign users to groups to control their access to specific resources or functionalities within Opsera.

• Implement Role-Based Access Control (RBAC): Group users and manage permissions efficiently by controlling access based on group memberships.

• Bulk Update Group Memberships: Add multiple users to a group in a single request to streamline permission management.

• Automate User Onboarding Processes: Automatically assign new users to appropriate groups during the onboarding process.

---

Required Access

• API Scopes: api, api-readonly

• Site Roles: Opsera Administrator, Administrator, Power User

---

Process Details

• Group Validation: The system validates the groupName parameter to ensure it meets the group name validation rules.

• Group Existence Check: Verifies that the specified group exists within the organization.

• Member Validation:

  • Confirms that the members array is provided and properly formatted.

  • Ensures all identifiers are either valid email addresses or unique database ID strings.

  • Checks that identifiers are not mixed types (all emails or all user IDs).

  • Removes duplicate identifiers.

• User Existence Verification: Checks that all provided identifiers correspond to valid users in the system.

• Group Membership Update:

  • Retrieves the current members of the group.

  • Removes specified members from the group.

  • Skips members not found in the group.

• Response Generation: Returns a success message with the list of members that were removed.

---

Important Notes!

• Group Name Matching: The groupName must match exactly (case-sensitive) and adhere to the group name validation rules.

• Identifier Types: You must provide either all email addresses or all user IDs, not a mix of both.

• Valid Users: All identifiers must belong to valid users in the system.

• Duplicate Handling: Duplicate identifiers will be automatically removed.

• Existing Members: Members already in the group will be skipped.

• Identifier Formats:

  • Email Addresses: Must be in a valid email format.

  • User IDs: Must be valid unique database ID format.

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

groupNamestringRequired

The name of the group to add members to (case-sensitive)

Example: developers-team

Bodyone of[]

application/json

List of identifiers (either all email addresses or all userIds) of members to add

string · emailOptional

Email address of a user

or

string · databaseIdOptional

Unique Opsera User ID

Responses

200

Members added successfully

application/json

messagestringOptional

Success message

Example: Group membership update completed successfully

resultstringOptional

Detailed result of the operation

Example: Members added successfully

addedMembersstring[]Optional

List of identifiers that were successfully added

Example: ["[email protected]","[email protected]"]

400

Bad request (invalid input)

application/json

404

Group not found

application/json

500

Internal server error

application/json

patch

/api/v2/usermanagement/group/{groupName}/members

HTTPcURLJavaScriptPython

PATCH /api/v2/usermanagement/group/{groupName}/members HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

[
  "[email protected]",
  "[email protected]"
]

Add members using email addressesAdd members using user IDs

{
  "message": "Group membership update completed successfully",
  "result": "Members added successfully",
  "addedMembers": [
    "[email protected]",
    "[email protected]"
  ]
}