---
title: "Get user groups"
method: GET
path: "/authz2/v1/users/{user_id}/groups"
tags: ["esper_cloud_api_User"]
---

# Get user groups

`GET /authz2/v1/users/{user_id}/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

## Path parameters

- `user_id` string, uuid, required

## Query parameters

- `sub_groups` boolean

## Response `200`

User Groups

- EsperCloudApiUserGroups
  - `group_ids` string[]
  - `has_all_group_access` boolean

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden, no permission to perform this action.

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/versions/e1f64cbb488e/schema)