Admin user search
Users
Admin user search
Search + filter user accounts with free-text query, status filters, and opaque cursor pagination.
GET
Admin user search
Overview
The user-management list view. Combines a free-text query, several status filters, and cursor pagination into a single read. Available to any admin role (SUPER, MODERATOR, FINANCE) — it is read-only.Authentication
Bearer <accessToken> required, where the token has scope: 'admin' (issued by /admin/auth/mfa-verify). The requireAdmin middleware rejects any user-scope token with 401 UNAUTHENTICATED.
Read-only — all three admin roles (SUPER, MODERATOR, FINANCE) may call this endpoint. No per-route role gate.
Path parameters
None.Query parameters
| Name | Type | Required | Notes | Example |
|---|---|---|---|---|
q | string | no | Free-text search across email, firstName, lastName. Matched via a case-insensitive anchored regex, and capped at 100 chars (longer values are rejected with VALIDATION_FAILED) to bound regex cost. | jane |
status | enum | no | ACTIVE, BANNED, or SUSPENDED. | BANNED |
tenancyStatus | enum | no | NOT_SUBMITTED, PENDING, APPROVED, REJECTED. | PENDING |
hasActiveSub | boolean | no | true/false. Filters by whether the user currently has an active subscription. | true |
cursor | string | no | Opaque base64url pagination cursor returned as nextCursor from a previous page. 1..512 chars. Do not construct or parse it. | eyJjcmVhdGVkQXQ… |
limit | integer | no | Page size, 1..100. Default 25. | 50 |
Request body
None.Response — 200 OK
| Field | Type | Notes |
|---|---|---|
items | array | Array of user summary objects (below). |
nextCursor | string | null | Opaque cursor for the next page, or null when this is the last page. |
User summary object
| Field | Type | Notes |
|---|---|---|
id | string | User ObjectId. |
email | string | |
firstName | string | null | |
lastName | string | null | |
status | enum | ACTIVE | BANNED | SUSPENDED. |
tenancyStatus | enum | NOT_SUBMITTED | PENDING | APPROVED | REJECTED. |
subscriptionStatus | string | Denormalised subscription status (e.g. ACTIVE, TRIALING, NONE). |
bannedAt | string | null | ISO timestamp of the ban, or null. |
bannedReason | string | null | Reason recorded at ban time, or null. |
createdAt | string | ISO timestamp. |
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | q over 100 chars, limit out of 1..100, or an enum filter has an unknown value. |
| 401 | UNAUTHENTICATED | Missing, malformed, expired, or non-admin-scope token. |
Example error — 401 UNAUTHENTICATED
See also
- Ban user — moderation action on a result row.
- Pagination — the opaque-cursor contract.
curl
Postman
Seedocs/postman/swappr.postman_collection.json → Admin Users → Search.