Skip to content
Docs
Members
List

List group members

API Reference
Zones
Groups
Members

List group members

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

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 federated credential 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 ParametersExpand Collapse
zoneId: string
groupId: string
Query ParametersExpand Collapse
after: optional string

Cursor for forward pagination

minLength1
maxLength255
before: optional string

Cursor for backward pagination

minLength1
maxLength255
"expand[]": optional "total_count" or "user" or array of "total_count" or "user"
Accepts one of the following:
UnionMember0 = "total_count" or "user"
Accepts one of the following:
"total_count"
"user"
UnionMember1 = array of "total_count" or "user"
Accepts one of the following:
"total_count"
"user"
"filter[id]": optional string or array of string

Restrict results to the member with this user ID. Repeatable, max 100. Mutually exclusive with after/before.

Accepts one of the following:
UnionMember0 = string

Restrict results to the member with this user ID. Repeatable, max 100. Mutually exclusive with after/before.

UnionMember1 = array of string
limit: optional number

Maximum number of items to return

minimum1
maximum100
"query[]": optional string or array of string

Search members by their user's email or federated credential subject (substring match)

Accepts one of the following:
UnionMember0 = string

Search members by their user's email or federated credential subject (substring match)

UnionMember1 = array of string
ReturnsExpand Collapse
items: array of GroupMember { created_at, user_id, user }
created_at: string

Entity creation timestamp

formatdate-time
user_id: string

ID of the user

user: optional User { id, created_at, email, 15 more }

An authenticated user entity

id: string

Unique identifier of the user

created_at: string

Entity creation timestamp

formatdate-time
email: string

Email address of the user

formatemail
email_verified: boolean

Whether the email address has been verified

identifier: string

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.

organization_id: string

Organization that owns this user

status: "active" or "disabled"

Status of the user. Disabled users cannot authenticate.

Accepts one of the following:
"active"
"disabled"
updated_at: string

Entity update timestamp

formatdate-time
zone_id: string

Zone this user belongs to

authenticated_at: optional string

Date when the user was last authenticated

credentials: optional array of object { created_at, provider_id, type, 4 more } or object { created_at, type, updated_at }

Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when expand[]=credentials is set on the listing endpoint.

Accepts one of the following:
IamUserCredentialFederation = object { created_at, provider_id, type, 4 more }

Federation credential: the user authenticates through an identity provider.

created_at: string

Entity creation timestamp

formatdate-time
provider_id: string

ID of the identity provider backing this credential. null when the source provider has been deleted.

type: "federation"
updated_at: string

Entity update timestamp

formatdate-time
issuer: optional string

Issuer identifier of the identity provider.

provider: optional Provider { id, created_at, identifier, 12 more }

A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate.

id: string

Unique identifier of the provider

created_at: string

Entity creation timestamp

formatdate-time
identifier: string

User specified identifier, unique within the zone

minLength1
maxLength2048
name: string

Human-readable name

minLength1
maxLength255
organization_id: string

Organization that owns this provider

owner_type: "platform" or "customer"

Who owns this provider. Platform-owned providers cannot be modified via API.

Accepts one of the following:
"platform"
"customer"
slug: string

URL-safe identifier, unique within the zone

minLength1
maxLength63
updated_at: string

Entity update timestamp

formatdate-time
zone_id: string

Zone this provider belongs to

client_id: optional string

OAuth 2.0 client identifier

client_secret_set: optional boolean

Indicates whether a client secret is configured

description: optional string

Human-readable description

maxLength2048
metadata: optional object { icon_url }

Provider metadata

icon_url: optional string

Icon URL

formaturi
maxLength2048
protocols: optional object { oauth2, openid }

Protocol-specific configuration

oauth2: optional object { issuer, authorization_endpoint, authorization_parameters, 10 more }

OAuth 2.0 protocol configuration

issuer: string

OIDC issuer URL used for discovery and token validation.

formaturi
authorization_endpoint: optional string
formaturi
authorization_parameters: optional map[string]

Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline).

authorization_resource_enabled: optional boolean

Whether to include the resource parameter in authorization requests.

authorization_resource_parameter: optional string

The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true.

code_challenge_methods_supported: optional array of string
jwks_uri: optional string
formaturi
registration_endpoint: optional string
formaturi
scope_parameter: optional string

The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope".

scope_separator: optional string

The separator character for scope values. Defaults to " " (space). Slack v2 uses ",".

scopes_supported: optional array of string
token_endpoint: optional string
formaturi
token_response_access_token_pointer: optional string

Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token".

openid: optional object { external_id_claim, scopes, single_logout_enabled, 2 more }

OpenID Connect protocol configuration

external_id_claim: optional string

Name of the OIDC claim carrying the stable external id used to correlate logins with externally provisioned (SCIM) users. Defaults to "sub". Set to "oid" for Entra, whose pairwise "sub" differs from the SCIM externalId.

scopes: optional array of string

Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email).

single_logout_enabled: optional boolean

When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false.

user_identifier_claim: optional string

Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. When not set, the user's Keycard ID is used.

userinfo_endpoint: optional string
formaturi
type: optional "external" or "keycard-vault" or "keycard-sts"
Accepts one of the following:
"external"
"keycard-vault"
"keycard-sts"
subject: optional string

Subject identifier from the identity provider.

IamUserCredentialPassword = object { created_at, type, updated_at }

Password credential: the user authenticates with email and password. The email lives on the user.

created_at: string

Entity creation timestamp

formatdate-time
type: "password"
updated_at: string

Entity update timestamp

formatdate-time
grant_count: optional number

Delegated-grant count for this user. Populated only when expand[]=grant_count is set on the listing endpoint.

minimum0
groups: optional array of object { id, identifier, name }

Groups this user belongs to within the zone. Populated only when expand[]=groups is set on the listing endpoint.

id: string

Unique identifier of the group

identifier: string

Zone-unique slug that policy rules match on.

name: string

Human-readable group name

issuer: optional string

Issuer identifier of the identity provider

provider_id: optional string

Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted.

role_assignments: optional array of object { role_id, role_identifier, role_owner_type, 3 more }

Role grants for this user within the zone. Populated only when expand[]=role-assignments is set on the listing endpoint.

role_id: string

ID of the assigned role

role_identifier: string

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.

minLength1
maxLength255
role_owner_type: "platform" or "customer"

Owner type of the granted role. Disambiguates roles that share an identifier across owner types.

Accepts one of the following:
"platform"
"customer"
scope: object { id, type }

The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself).

id: string

The ID of the scoped resource.

type: string

The kind of resource this grant is scoped to (e.g. zone).

source: "user" or "group"

The principal that holds this grant: user when assigned directly to the user, or group when inherited through group membership.

Accepts one of the following:
"user"
"group"
group_id: optional string

ID of the group this grant is inherited from. Present only when source is group.

session_count: optional number

Session count for this user. Populated only when expand[]=session_count is set on the listing endpoint.

minimum0
subject: optional string

Subject identifier from the identity provider

List group members

curl https://api.keycard.ai/zones/$ZONE_ID/groups/$GROUP_ID/members \
    -H "Authorization: Bearer $KEYCARD_API_API_KEY"
{
  "items": [
    {
      "created_at": "2019-12-27T18:11:19.117Z",
      "user_id": "user_id",
      "user": {
        "id": "id",
        "created_at": "2019-12-27T18:11:19.117Z",
        "email": "dev@stainless.com",
        "email_verified": true,
        "identifier": "identifier",
        "organization_id": "organization_id",
        "status": "active",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "zone_id": "zone_id",
        "authenticated_at": "authenticated_at",
        "credentials": [
          {
            "created_at": "2019-12-27T18:11:19.117Z",
            "provider_id": "provider_id",
            "type": "federation",
            "updated_at": "2019-12-27T18:11:19.117Z",
            "issuer": "issuer",
            "provider": {
              "id": "id",
              "created_at": "2019-12-27T18:11:19.117Z",
              "identifier": "x",
              "name": "x",
              "organization_id": "organization_id",
              "owner_type": "platform",
              "slug": "slug",
              "updated_at": "2019-12-27T18:11:19.117Z",
              "zone_id": "zone_id",
              "client_id": "client_id",
              "client_secret_set": true,
              "description": "description",
              "metadata": {
                "icon_url": "https://example.com"
              },
              "protocols": {
                "oauth2": {
                  "issuer": "https://example.com",
                  "authorization_endpoint": "https://example.com",
                  "authorization_parameters": {
                    "foo": "string"
                  },
                  "authorization_resource_enabled": true,
                  "authorization_resource_parameter": "authorization_resource_parameter",
                  "code_challenge_methods_supported": [
                    "string"
                  ],
                  "jwks_uri": "https://example.com",
                  "registration_endpoint": "https://example.com",
                  "scope_parameter": "scope_parameter",
                  "scope_separator": "scope_separator",
                  "scopes_supported": [
                    "string"
                  ],
                  "token_endpoint": "https://example.com",
                  "token_response_access_token_pointer": "token_response_access_token_pointer"
                },
                "openid": {
                  "external_id_claim": "external_id_claim",
                  "scopes": [
                    "string"
                  ],
                  "single_logout_enabled": true,
                  "user_identifier_claim": "user_identifier_claim",
                  "userinfo_endpoint": "https://example.com"
                }
              },
              "type": "external"
            },
            "subject": "subject"
          }
        ],
        "grant_count": 0,
        "groups": [
          {
            "id": "id",
            "identifier": "identifier",
            "name": "name"
          }
        ],
        "issuer": "issuer",
        "provider_id": "provider_id",
        "role_assignments": [
          {
            "role_id": "role_id",
            "role_identifier": "role_identifier",
            "role_owner_type": "platform",
            "scope": {
              "id": "id",
              "type": "type"
            },
            "source": "user",
            "group_id": "group_id"
          }
        ],
        "session_count": 0,
        "subject": "subject"
      }
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}
Returns Examples
{
  "items": [
    {
      "created_at": "2019-12-27T18:11:19.117Z",
      "user_id": "user_id",
      "user": {
        "id": "id",
        "created_at": "2019-12-27T18:11:19.117Z",
        "email": "dev@stainless.com",
        "email_verified": true,
        "identifier": "identifier",
        "organization_id": "organization_id",
        "status": "active",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "zone_id": "zone_id",
        "authenticated_at": "authenticated_at",
        "credentials": [
          {
            "created_at": "2019-12-27T18:11:19.117Z",
            "provider_id": "provider_id",
            "type": "federation",
            "updated_at": "2019-12-27T18:11:19.117Z",
            "issuer": "issuer",
            "provider": {
              "id": "id",
              "created_at": "2019-12-27T18:11:19.117Z",
              "identifier": "x",
              "name": "x",
              "organization_id": "organization_id",
              "owner_type": "platform",
              "slug": "slug",
              "updated_at": "2019-12-27T18:11:19.117Z",
              "zone_id": "zone_id",
              "client_id": "client_id",
              "client_secret_set": true,
              "description": "description",
              "metadata": {
                "icon_url": "https://example.com"
              },
              "protocols": {
                "oauth2": {
                  "issuer": "https://example.com",
                  "authorization_endpoint": "https://example.com",
                  "authorization_parameters": {
                    "foo": "string"
                  },
                  "authorization_resource_enabled": true,
                  "authorization_resource_parameter": "authorization_resource_parameter",
                  "code_challenge_methods_supported": [
                    "string"
                  ],
                  "jwks_uri": "https://example.com",
                  "registration_endpoint": "https://example.com",
                  "scope_parameter": "scope_parameter",
                  "scope_separator": "scope_separator",
                  "scopes_supported": [
                    "string"
                  ],
                  "token_endpoint": "https://example.com",
                  "token_response_access_token_pointer": "token_response_access_token_pointer"
                },
                "openid": {
                  "external_id_claim": "external_id_claim",
                  "scopes": [
                    "string"
                  ],
                  "single_logout_enabled": true,
                  "user_identifier_claim": "user_identifier_claim",
                  "userinfo_endpoint": "https://example.com"
                }
              },
              "type": "external"
            },
            "subject": "subject"
          }
        ],
        "grant_count": 0,
        "groups": [
          {
            "id": "id",
            "identifier": "identifier",
            "name": "name"
          }
        ],
        "issuer": "issuer",
        "provider_id": "provider_id",
        "role_assignments": [
          {
            "role_id": "role_id",
            "role_identifier": "role_identifier",
            "role_owner_type": "platform",
            "scope": {
              "id": "id",
              "type": "type"
            },
            "source": "user",
            "group_id": "group_id"
          }
        ],
        "session_count": 0,
        "subject": "subject"
      }
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}