---
title: "List group members"
method: GET
path: "/zones/{zoneId}/groups/{groupId}/members"
tags: ["Groups"]
---

# List group members

`GET /zones/{zoneId}/groups/{groupId}/members`

## Request

- Base URL: `https://docs.keycard.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.keycard.ai/zones/{zoneId}/groups/{groupId}/members`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `/service-account-token`

Returns a paginated list of the group's members. Use cursor pagination via `after`/`before`. Pass `expand[]=user` to embed each member's full user record and `expand[]=total_count` to include the matching row count. Pass `query[]` (repeatable, 1-255 chars) to search members by their user's email or `subject` (substring match, OR'd across repeated values). Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of members by user ID — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested member that exists in the group, in a single page. IDs not in the group are silently omitted.

## Path parameters

- `zoneId` string, required
- `groupId` string, required

## Query parameters

- `after` string
- `before` string
- `limit` integer
- `expand[]` union
  - 'total_count' | 'user'
  - string[]
- `filter[id]` union
  - string: Restrict results to the member with this user ID. Repeatable, max 100. Mutually exclusive with after/before.
  - string[]
- `query[]` union
  - string: Search members by their user's email or `subject` (substring match)
  - string[]

## Response `200`

Default Response

- object
  - `items` IamGroupMember[], required
    - `user_id` string, required: ID of the user
    - `created_at` string, date-time, required: Entity creation timestamp
    - `user` IamUser: An authenticated user entity
      - `id` string, required: Unique identifier of the user
      - `organization_id` string, required: Organization that owns this user
      - `zone_id` string, required: Zone this user belongs to
      - `identifier` string, required: Zone-scoped user identifier. Defaults to the user's Keycard ID. When the provider has user_identifier_claim configured, the value is set from that claim at user creation time.
      - `subject` string: Subject identifier from the identity provider
      - `issuer` string: Issuer identifier of the identity provider
      - `email` string, email, required: Email address of the user
      - `email_verified` boolean, required: Whether the email address has been verified
      - `status` 'active' | 'disabled', required: Status of the user. Disabled users cannot authenticate.
      - `external` boolean, required: Whether the user is synced from an external directory over SCIM. When true the user is directory-owned: `status` cannot be changed and the user cannot be deleted through this API while the zone has `external_sync_enabled` set.
      - `provider_id` string: Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted.
      - `created_at` string, date-time, required: Entity creation timestamp
      - `updated_at` string, date-time, required: Entity update timestamp
      - `authenticated_at` string: Date when the user was last authenticated
      - `session_count` integer: Session count for this user. Populated only when `expand[]=session_count` is set on the listing endpoint.
      - `grant_count` integer: Delegated-grant count for this user. Populated only when `expand[]=grant_count` is set on the listing endpoint.
      - `role_assignments` IamUserRoleAssignment[]: Role grants for this user within the zone. Populated only when `expand[]=role-assignments` is set on the listing endpoint.
        - `role_id` string, required: ID of the assigned role
        - `role_identifier` string, required: Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.
        - `role_owner_type` 'platform' | 'customer', required: Owner type of the granted role. Disambiguates roles that share an identifier across owner types.
        - `scope` object, nullable, required: The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself).
          - `type` string, required: The kind of resource this grant is scoped to (e.g. `zone`).
          - `id` string, required: The ID of the scoped resource.
        - `source` 'user' | 'group', required: The principal that holds this grant: `user` when assigned directly to the user, or `group` when inherited through group membership.
        - `group_id` string: ID of the group this grant is inherited from. Present only when `source` is `group`.
      - `groups` IamUserGroup[]: Groups this user belongs to within the zone. Populated only when `expand[]=groups` is set on the listing endpoint.
        - `id` string, required: Unique identifier of the group
        - `identifier` string, required: Zone-unique slug that policy rules match on.
        - `name` string, required: Human-readable group name
        - `external` boolean, required: Whether the group is synced from an external directory. When true the group is directory-owned and its membership is read-only; when false it is managed in Keycard.
        - `external_issuer` string, nullable, required: Issuer of the external directory the group was synced from. `null` for groups managed in Keycard. Read-only: set by external sync, never by the caller.
      - `credentials` IamUserCredential[]: Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when `expand[]=credentials` is set on the listing endpoint.
        - union: An authentication credential belonging to a user.
          - IamUserCredentialFederation: Common fields shared by all user credential types
            - `created_at` string, date-time, required: Entity creation timestamp
            - `updated_at` string, date-time, required: Entity update timestamp
            - `type` 'federation', required
            - `subject` string: Subject identifier from the identity provider.
            - `issuer` string: Issuer identifier of the identity provider.
            - `provider_id` string, nullable, required: ID of the identity provider backing this credential. `null` when the source provider has been deleted.
            - `provider` IamProvider: A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate.
              - …
          - IamUserCredentialPassword: Common fields shared by all user credential types
            - `created_at` string, date-time, required: Entity creation timestamp
            - `updated_at` string, date-time, required: Entity update timestamp
            - `type` 'password', required
  - `pagination` IamPagination, required: Cursor-based pagination metadata
    - `after_cursor` string, required: An opaque cursor used for paginating through a list of results
    - `before_cursor` string, required: An opaque cursor used for paginating through a list of results
    - `total_count` integer: Total number of items matching the query. Only included when expand[]=total_count is requested.

## Other responses

- `404`: Error response
- `default`: Error response

## Changes

- **2026-10-16** `0cfaff865771`: 1 warning, 3 info
  - removed the optional property `items/items/user/allOf[subschema #1: User]/credentials/items/anyOf[subschema #1: User Credential Federation]/allOf[subschema #2]/provider/allOf[subschema #1: Provider]/protocols/openid/external_id_claim` from the response with the `200` status
  - added the required property `items/items/user/allOf[subschema #1: User]/external` to the response with the `200` status
  - added the required property `items/items/user/allOf[subschema #1: User]/groups/items/external` to the response with the `200` status
  - added the required property `items/items/user/allOf[subschema #1: User]/groups/items/external_issuer` to the response with the `200` status
- **2026-08-26** `d65d51379d93`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/changes/zones/:zoneId/groups/:groupId/members/get.md)

---

[API](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api.md) - [All operations](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/revisions/0dee67e0a73a?raw)