ZitadelDocs

Query users

Returns the users of a project, paginated with a cursor. `project_id` names the project to list; without it, the credential's own project is listed. Accepts either a project secret (`oauth2`) or a user-bound Console session cookie (`nextgenSession`). Cookie-authenticated requests follow the scheme's CSRF rules (`nextgenSession`).

POST
/users/query

Returns the users of a project, paginated with a cursor.

project_id names the project to list; without it, the credential's own project is listed.

Accepts either a project secret (oauth2) or a user-bound Console session cookie (nextgenSession). Cookie-authenticated requests follow the scheme's CSRF rules (nextgenSession).

Authorization

headerAuthorizationBearer <token>

Scope: user.read

Query Parameters

project_id?string

The project the request addresses. Omit it to address the credential's own project.

Match^[a-zA-Z0-9_-]+$

Request Body

Request to query the users of a project.

application/json
  1. body

Request to query the users of a project.

limit?limit
Range1 <= value <= 100
Default20
page_token?|

Token to retrieve the next page of results. Must be sent with the same sorting as the request that issued the token. Omitting sorting reuses the default sort and only succeeds when that default matches the token.

expand?array<>

Related collections to embed on each user (ADR 059). Omit it and no embedded collection is returned. An unrecognised value is rejected.

sorting?
filter?array<>

Filter criteria for querying users. Criteria are combined with AND.

Response Body

The list of users was returned successfully

application/json
  1. response

Paginated list of users.

users*array<>
next_page_token?|

Token to pass as page_token in the next request to fetch the following page. Absent when there are no more results.

curl -X POST 'https://example.com/users/query' \  -H 'Content-Type: application/json' \  -d '{}'
{  "users": [    {      "id": "string",      "schema": "string",      "attributes": {},      "metadata": {        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z",        "status": "active",        "lifecycle_owner_team_id": "string",        "lifecycle_owner_team": {          "id": "string",          "name": "string",          "status": "active",          "created_at": "2019-08-24T14:15:22Z",          "updated_at": "2019-08-24T14:15:22Z"        }      },      "identifier": "string",      "identifier_property": "string",      "display": "string",      "teams": [        {          "id": "string",          "name": "string",          "membership_status": "pending",          "created_at": "2019-08-24T14:15:22Z",          "updated_at": "2019-08-24T14:15:22Z"        }      ],      "teams_truncated": true    }  ],  "next_page_token": "string"}