Users (platform admin)

Cross-organization user search and single-user reads for operators, plus an MFA reset for account recovery. These are low-frequency operator endpoints and use offset pagination ({ items, total, page, page_size }).

::: tip Auth

• GET /v1/admin/users — any platform admin.
• GET /v1/users/:id — a platform admin, or the user reading their own record.
• POST /v1/admin/users/:id/mfa/reset — platform Admin or higher. :::

---

GET /v1/admin/users

Search users across every organization.

Request

GET /v1/admin/users?q=<term>&page=<n>&page_size=<n>

Query param	Type	Notes
q	string	Free-text term matched case-insensitively against email and display_name. Blank/absent lists all users.
page	int	1-indexed. Defaults to 1.
page_size	int	Defaults to 25, clamped to [1, 100].

Response

200 OK

{
  "items": [
    {
      "id": "a3f1…",
      "email": "[email protected]",
      "display_name": "Alice",
      "organization_id": "f47a…",
      "job_title": null,
      "phone_number": null,
      "avatar_url": null,
      "bio": null,
      "preferences": null,
      "mfa_enabled": true,
      "passkey_enabled": false,
      "email_verified": true,
      "last_password_change": "2026-05-01T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 25
}

Each items[] element is the same ProfileView returned by GET /v1/users/me. The envelope fields:

Field	Type	Meaning
items	array	Users on this page.
total	int	Total matches across all pages.
page	int	1-indexed page returned.
page_size	int	Page size used.

---

GET /v1/users/:id

Fetch a single user by id. A platform admin may read any user; a non-admin may only read their own record (any other id returns 403).

Request

GET /v1/users/:id

Path param	Type	Notes
id	UUID	The user id.

Response

200 OK

A single ProfileView object (same shape as an items[] element above).

---

POST /v1/admin/users/:id/mfa/reset

Clear a user's MFA enrollment — the account-recovery path when a user loses their authenticator. Platform Admin only. The reset is recorded in the audit log, attributed to the acting admin and scoped to the target's organization.

Request

POST /v1/admin/users/:id/mfa/reset

Path param	Type	Notes
id	UUID	The user whose MFA to clear.

No body.

Response

204 No Content

MFA is cleared. The user can re-enroll on next sign-in. Idempotent — resetting a user who has no MFA is a no-op.

---

Error responses

Status	Code	When
401	authentication_required	No valid auth credential.
403	forbidden	Not a platform admin (or, for GET /v1/users/:id, reading someone else's record without admin rights).
403	csrf_failed	Cookie-authed POST without a valid X-IdentSphere-CSRF header.
404	not_found	No such user.