Users (Admin)
Admin-level user management — list, read, modify, and delete any user record. Self-service flows for the currently authenticated user live under Self; user-account flows that operate before sign-in (password recovery) live under User Account.
Scopes
| Scope | Reach |
|---|---|
users:read | Listing, reading, viewing filters. |
users:write | Modifying users, managing avatars, unlocking accounts, uniqueness checks. |
admin | Creating users (users:write alone is not sufficient — see Create User). |
Endpoints
List Users
GET /api/admin/users/
Returns a page of user records.
Required scope: users:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — UserInDbCursorPage
Get User Filter Metadata
GET /api/admin/users/filters
Returns filter/operator/sort options for List Users.
Required scope: users:read
Response 200 — open metadata object.
Get User by ID
GET /api/admin/users/{id}
Returns a single user record.
Required scope: users:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | User ID. |
Response 200 — UserRead
Create User
POST /api/admin/users/
Creates a new user record.
Required scope: admin
TIP
User creation is restricted to the admin scope by design — users:write alone is not sufficient. This includes inviting external users.
Request body — UserWriteCreate
Response 201 — UserRead
Update User by ID
PUT /api/admin/users/{id}
Replaces the user record.
Required scope: users:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | User ID. |
Request body — UserWriteReplace
Response 200 — UserRead
Patch User
PATCH /api/admin/users/{id}
Partial user update.
Required scope: users:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | User ID. |
Request body — UserWriteUpdate
Response 200 — UserRead
Delete User by ID
DELETE /api/admin/users/{id}
Removes a user record. All active sessions for that user are invalidated.
Required scope: users:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | User ID. |
Response 204 — empty.
Set User Avatar
POST /api/admin/users/{id}/avatar
Uploads or replaces a user's avatar. Active only in development or debug modes — production deployments serve avatars through cached static URLs.
Required scope: users:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | User ID. |
Request body — Body_Users-Set_User_Avatar (multipart/form-data).
Response 200 — UserRead
Delete User Avatar
DELETE /api/admin/users/{id}/avatar
Removes a user's avatar. Active only in development or debug modes.
Required scope: users:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | User ID. |
Response 200 — UserRead
Unlock User
POST /api/admin/users/{id}/unlock
Clears a user's account-lock flag (set when too many failed sign-in attempts occur). Active only in development or debug modes — production lockouts auto-clear by policy.
Required scope: users:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | User ID. |
Response 200 — UserRead
Check Email Unique
GET /api/admin/users/check-email-unique?email=<email>
Pre-flight uniqueness check used by user-creation UIs. Returns whether the supplied email is available for use.
Required scope: users:write
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
email | string | yes | Email to check. |
Response 200 — { unique: bool }-style payload.
Check Login Unique
GET /api/admin/users/check-login-unique?login=<login>
Pre-flight uniqueness check for a user's login identifier.
Required scope: users:write
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
login | string | yes | Login to check. |
Response 200 — { unique: bool }-style payload.
See also
- Self — endpoints scoped to the currently authenticated user.
- User Account — pre-sign-in flows (password recovery, token verification).
- Groups — assigning users to groups.
- Scope Sets — attaching named scope bundles to users.