Skip to content
Docs
Users
List

List users

API Reference
Zones
Users

List users

client.Zones.Users.List(ctx, zoneID, query) (*ZoneUserListResponse, error)
GET/zones/{zoneId}/users

Returns a list of users in the specified zone.

Rollout note: the paginated/searchable/sortable behavior described below is gated behind the user-pagination feature flag and is currently disabled for most zones. While the flag is off, the response returns every user in the zone (capped at 100) in items and a fixed pagination envelope where after_cursor and before_cursor are null and total_count is 0. The query parameters below are accepted but ignored. The flag is rolled out per-zone in Datadog and will become the default once Console adopts the paginated contract.

Use cursor pagination via after/before. Sort: comma-separated field list; prefix with - for descending. Use expand[]=total_count to include the matching row count, expand[]=session_count to include per-user session counts, expand[]=grant_count to include per-user delegated-grant counts, and expand[]=role-assignments to include each user's structured role grants. Filter by exact email via filter[email]; search via query[email] / query[subject] / query[] (substring match, OR'd across repeated values). query[] matches against email and federation credential subject. Pass filter[id] (repeatable, max 100) to restrict results to a known set of users — mutually exclusive with after/before (returns 400 if combined). When filter[id] is set, limit is ignored and the response contains every requested user that exists in the zone, in a single page. IDs not in the zone are silently omitted.

ParametersExpand Collapse
zoneID string
query ZoneUserListParams
After param.Field[string]optional

Cursor for forward pagination

minLength1
maxLength255
Before param.Field[string]optional

Cursor for backward pagination

minLength1
maxLength255
Expand param.Field[ZoneUserListParamsExpandUnion]optional
type ZoneUserListParamsExpandString string
Accepts one of the following:
const ZoneUserListParamsExpandStringTotalCount ZoneUserListParamsExpandString = "total_count"
const ZoneUserListParamsExpandStringSessionCount ZoneUserListParamsExpandString = "session_count"
const ZoneUserListParamsExpandStringGrantCount ZoneUserListParamsExpandString = "grant_count"
const ZoneUserListParamsExpandStringRoleAssignments ZoneUserListParamsExpandString = "role-assignments"
type ZoneUserListParamsExpandArray []string
Accepts one of the following:
const ZoneUserListParamsExpandArrayItemTotalCount ZoneUserListParamsExpandArrayItem = "total_count"
const ZoneUserListParamsExpandArrayItemSessionCount ZoneUserListParamsExpandArrayItem = "session_count"
const ZoneUserListParamsExpandArrayItemGrantCount ZoneUserListParamsExpandArrayItem = "grant_count"
const ZoneUserListParamsExpandArrayItemRoleAssignments ZoneUserListParamsExpandArrayItem = "role-assignments"
FilterEmail param.Field[ZoneUserListParamsFilterEmailUnion]optional

Filter by exact email address

string
type ZoneUserListParamsFilterEmailArray []string
FilterID param.Field[ZoneUserListParamsFilterIDUnion]optional

Restrict results to users with this publicId. Repeatable, max 100. Mutually exclusive with after/before.

string
type ZoneUserListParamsFilterIDArray []string
Limit param.Field[int64]optional

Maximum number of items to return

minimum1
maximum100
Query param.Field[ZoneUserListParamsQueryUnion]optional

Search across email and credential subject (substring match)

string
type ZoneUserListParamsQueryArray []string
QueryEmail param.Field[ZoneUserListParamsQueryEmailUnion]optional

Search by email (substring match)

string
type ZoneUserListParamsQueryEmailArray []string
QuerySubject param.Field[ZoneUserListParamsQuerySubjectUnion]optional

Search by federated credential subject (substring match)

string
type ZoneUserListParamsQuerySubjectArray []string
Sort param.Field[string]optional

Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, email, authenticated_at

ReturnsExpand Collapse
type ZoneUserListResponse struct{…}
Items []User
ID string

Unique identifier of the user

CreatedAt Time

Entity creation timestamp

formatdate-time
Email string

Email address of the user

formatemail
EmailVerified bool

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.

OrganizationID string

Organization that owns this user

Status UserStatus

Status of the user. Disabled users cannot authenticate.

Accepts one of the following:
const UserStatusActive UserStatus = "active"
const UserStatusDisabled UserStatus = "disabled"
UpdatedAt Time

Entity update timestamp

formatdate-time
ZoneID string

Zone this user belongs to

AuthenticatedAt stringoptional

Date when the user was last authenticated

GrantCount int64optional

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

minimum0
Issuer stringoptional

Issuer identifier of the identity provider

ProviderID stringoptional

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

RoleAssignments []UserRoleAssignmentoptional

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

RoleID string

ID of the assigned role

RoleIdentifier string

Opaque role identifier. Treated as an opaque identifier by the API and unique within a zone.

minLength1
maxLength255
Scope UserRoleAssignmentScope

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).

SessionCount int64optional

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

minimum0
Subject stringoptional

Subject identifier from the identity provider

List users

package main

import (
  "context"
  "fmt"

  "github.com/keycardai/keycard-go"
)

func main() {
  client := keycard.NewClient(

  )
  users, err := client.Zones.Users.List(
    context.TODO(),
    "zoneId",
    keycard.ZoneUserListParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", users.Items)
}

{
  "items": [
    {
      "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",
      "grant_count": 0,
      "issuer": "issuer",
      "provider_id": "provider_id",
      "role_assignments": [
        {
          "role_id": "role_id",
          "role_identifier": "x",
          "scope": {
            "id": "id",
            "type": "type"
          }
        }
      ],
      "session_count": 0,
      "subject": "subject"
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}
Returns Examples
{
  "items": [
    {
      "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",
      "grant_count": 0,
      "issuer": "issuer",
      "provider_id": "provider_id",
      "role_assignments": [
        {
          "role_id": "role_id",
          "role_identifier": "x",
          "scope": {
            "id": "id",
            "type": "type"
          }
        }
      ],
      "session_count": 0,
      "subject": "subject"
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}