Get user groups

Returns the device groups a specific user has access to, based on their role and group assignments.

Use this endpoint to audit a user's group-level access scope, or to determine which subgroups they can reach before assigning device commands or bulk operations.

About Get User Groups

This endpoint retrieves the group membership for a given user from Esper's authorization service, returning a list of group UUIDs and a flag indicating whether the user has access to all groups in the tenant. The user_id parameter expects the UUID-format authn_user_id. The optional sub_groups query parameter expands the response to include subgroups the user can reach through their group assignments, since users with access to a parent group automatically have access to its subgroups.

Key Fields

user_id — the UUID-format authn_user_id of the target user; obtain from GET /authn2/v1/users/

sub_groups — (query param, boolean) set to true to include subgroup access in the response

group_ids — returned array of group UUIDs the user has access to

has_all_group_access — if true, the user has access to all tenant groups regardless of the group_ids list

Common Use Cases

Auditing which device groups a user can manage before issuing group-level commands

Verifying group scope for AuthZ Role User accounts where access is controlled by a custom RBAC role

Confirming subgroup access inheritance when planning nested group structures

Best Practices

Use GET /authn2/v1/users/ to retrieve the target user's authn_user_id (UUID) before calling this endpoint — the integer id from GET /user/ will not work

Always call with sub_groups=true when you need a complete picture of a user's reachable device scope, not just their directly assigned groups

If has_all_group_access is true, the group_ids list is not the full scope — the user can access every group in the tenant

Workflow

Call GET /authn2/v1/users/ to retrieve the target user's authn_user_id

Call GET /authz2/v1/users/{user_id}/groups with sub_groups=true if subgroup access is relevant

Inspect group_ids and has_all_group_access to determine the user's full device group scope