API Reference

List Users (tenant)

Overview

Retrieve a paginated list of users that belong to the current tenant workspace.

Use query parameters to search, filter by role or active status, and match custom metadata fields. The response includes each user summary plus pagination metadata so you can build admin tables and infinite scroll UIs.

When to use this endpoint?

Use List Users when:

You need to display tenant users in an admin directory or members table.
You want to search users by name, email, or other searchable fields.
You are filtering by role, active status, or metadata.<key> values.
You need pagination details such as total count and next/previous page flags.

GET{baseUrl}/api/{apiVersion}/client/users?page=1&limit=10

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
is-tenant	true	Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.

Query Parameters

Parameter	Example	Description
page	1	Page number, 1-based. Default 1.
limit	10	Page size — items per page. Default 10.
search	—	Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint’s searchable fields.
role	user	Filter by tenant role slug (e.g. "admin", "user", "sales-manager"). Omit to use the endpoint default.
isActive	true	Filter by active status: "true" or "false".
metadata.tier	gold	Filter on custom metadata. Matches metadata.tier exactly — use any metadata.<yourKey>=value your app stores.

Success Response (HTTP 200 OK)

On success, the API returns a paginated list of users for the tenant.

json

{
  "success": true,
  "message": "Users fetched successfully",
  "data": {
    "list": [
      {
        "_id": "694b...d8",
        "name": "Will Smith",
        "email": "will.smith@example.com",
        "role": "user",
        "isActive": true,
        "isOnline": false,
        "lastSeen": "2026-06-18T08:55:00.000Z",
        "metadata": {
          "workspaceId": "c1"
        },
        "createdAt": "2026-06-01T00:00:00.000Z",
        "updatedAt": "2026-06-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 10,
      "hasNextPage": true,
      "hasPreviousPage": false,
      "pageSize": 10
    }
  },
  "error": null
}

Common Errors

HTTP 200 OK means the list was fetched successfully. Requests fail when tenant headers or authentication are missing or invalid.

Code	Reason
400 Bad Request	Required headers are missing or query parameters are invalid.
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching users.

Best Practices

Always send is-tenant: true and a valid x-client-id for tenant-scoped user lists.
Keep limit reasonable for UI tables; use pagination.hasNextPage to load more pages.
Prefer search and structured filters over fetching all users client-side.
Discover available metadata keys with Get User Metadata Keys before building metadata.<key> filters.
Refresh the list after create, update, or delete operations so the UI stays in sync.

Ready to browse users

With a valid Access Token and tenant headers, you can list users and open a single record with Get User Detail using the returned _id.

Header

Value

Description

is-tenant

true

Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).

x-client-id

Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.

Parameter

Example

Description

page

Page number, 1-based. Default 1.

limit

Page size — items per page. Default 10.

—

Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint’s searchable fields.

role

user

Filter by tenant role slug (e.g. "admin", "user", "sales-manager"). Omit to use the endpoint default.

isActive

true

Filter by active status: "true" or "false".

metadata.tier

gold

Filter on custom metadata. Matches metadata.tier exactly — use any metadata.<yourKey>=value your app stores.

{ "success": true, "message": "Users fetched successfully", "data": { "list": [ { "_id": "694b...d8", "name": "Will Smith", "email": "will.smith@example.com", "role": "user", "isActive": true, "isOnline": false, "lastSeen": "2026-06-18T08:55:00.000Z", "metadata": { "workspaceId": "c1" }, "createdAt": "2026-06-01T00:00:00.000Z", "updatedAt": "2026-06-01T00:00:00.000Z" } ], "pagination": { "currentPage": 1, "totalCount": 10, "hasNextPage": true, "hasPreviousPage": false, "pageSize": 10 } }, "error": null }

Code

Reason

400 Bad Request

Required headers are missing or query parameters are invalid.

401 Unauthorized

Access Token is missing, invalid, or expired.

500 Internal Server Error

An unexpected error occurred while fetching users.