API endpoint to list all group memberships for enterprise users (including groups outside organization hierarchy)

Problem to solve

As a GitLab group owner managing enterprise users, I need to identify all groups where an enterprise user has the Owner role before I can delete them. Currently, when attempting to delete an enterprise user via the API (DELETE /groups/:id/enterprise_users/:user_id), I receive the error:

{
  "message": "Can not remove a user who is the sole owner of a group."
}

However, there is no API endpoint that allows me to discover which groups the user is the sole owner of, especially when those groups exist outside my organization's group hierarchy.

The existing endpoint GET /groups/:id/billable_members/:user_id/memberships only shows memberships within the queried group's hierarchy, but enterprise users may be sole owners of:

  • Personal groups/projects
  • Groups outside the organization's top-level group
  • Subgroups created before enterprise user policies were enforced

This creates a blocker for enterprise user lifecycle management and cleanup operations.

Intended users

  • GitLab group owners managing enterprise users
  • IT administrators performing user lifecycle management
  • Security/compliance teams auditing user access

User experience goal

As a group owner, I want to:

  1. Query an API endpoint to see all groups where an enterprise user has the Owner role
  2. Identify which groups would block the user's deletion (where they are the sole owner)
  3. Take appropriate action (assign another owner, delete the group, etc.) before removing the enterprise user

Proposal

Add a new API endpoint or enhance the existing enterprise users API to provide complete visibility into group memberships:

Option 1: New endpoint

GET /groups/:id/enterprise_users/:user_id/all_memberships

Option 2: Enhance existing endpoint

GET /groups/:id/enterprise_users/:user_id/owner_groups

Response should include:

  • All groups where the user has Owner role (access_level: 50)
  • Indication of whether the user is the sole owner
  • Group full path and ID
  • Whether the group is within or outside the organization hierarchy

Example response:

[
  {
    "group_id": 123,
    "group_full_path": "my-organization/subgroup-1",
    "access_level": 50,
    "is_sole_owner": false,
    "within_hierarchy": true,
    "other_owners_count": 2
  },
  {
    "group_id": 456,
    "group_full_path": "user-personal-group",
    "access_level": 50,
    "is_sole_owner": true,
    "within_hierarchy": false,
    "other_owners_count": 0
  }
]

Permissions and Security

  • Only group owners of the top-level group should have access to this endpoint
  • This aligns with existing enterprise user management permissions
  • No additional security concerns as group owners already have visibility into enterprise user details

Availability & Testing

  • Should be available on GitLab.com (SaaS) where enterprise users feature exists
  • Tier: Premium, Ultimate (same as enterprise users feature)

What does success look like, and how can we measure that?

Success metrics:

  • Group owners can successfully identify blocking groups before attempting user deletion
  • Reduction in support tickets related to "cannot delete enterprise user" errors
  • Improved enterprise user lifecycle management workflows

Acceptance criteria:

  • API endpoint returns all groups where enterprise user has Owner role
  • Response indicates which groups would block user deletion (sole owner)
  • Endpoint respects existing enterprise user permissions model
  • Documentation includes examples for common use cases
  • API returns groups both inside and outside organization hierarchy

What is the type of buyer?

Enterprise customers using GitLab Premium/Ultimate with enterprise users feature enabled.

Is this a cross-stage feature?

No, this is primarily a Manage stage feature related to enterprise user management.

Links / references

Real-world use case

During enterprise user synchronization with an identity provider (such as Azure AD/EntraID), cleanup operations often identify users that cannot be deleted because they are sole owners of groups. Without an API to identify these groups, administrators must:

  1. Open support tickets for each affected user
  2. Wait for GitLab support to manually identify the blocking groups
  3. This delays user lifecycle management and compliance processes

Having this API endpoint would enable self-service management and faster resolution of these common operational scenarios.

Edited by 🤖 GitLab Bot 🤖