Users API
GET /api/v1/users
Section titled “GET /api/v1/users”List Users
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
POST /api/v1/users
Section titled “POST /api/v1/users”Create User
Request body (required), application/json, UserIn
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | null | no | |
email | string | yes | |
password | string | yes | |
role | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
DELETE /api/v1/users/{user_id}
Section titled “DELETE /api/v1/users/{user_id}”Delete User
RBAC: admin. No entitlement flag.
Delete an account outright.
Prefer PATCH is_active=false: audit rows carry actor_id, and deleting the user makes every action they ever took unattributable. This exists for the account that should never have been created.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user_id | path | integer | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
| 404 | user not found | |
| 409 | self_delete, or last_owner |
PATCH /api/v1/users/{user_id}
Section titled “PATCH /api/v1/users/{user_id}”Patch User
RBAC: admin. No entitlement flag.
Deactivate or reactivate an account, or fix its display name.
Deactivation rather than deletion is the normal path: it keeps the user’s audit rows attributable, which deletion cannot.
Setting is_active: false revokes every live session for that user immediately.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user_id | path | integer | yes |
Request body (required), application/json, UserPatchIn
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | null | no | |
is_active | boolean | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
| 404 | user not found | |
| 409 | self_deactivate, or last_owner | |
| 422 | nothing to change |
POST /api/v1/users/{user_id}/password
Section titled “POST /api/v1/users/{user_id}/password”Reset Password
RBAC: admin. No entitlement flag.
Set another user’s password.
An admin-set password is a recovery mechanism, not a login: every existing session is revoked so a stolen cookie cannot outlive the reset. The old password is never required, which is precisely why this is (“user”,“manage”) and audited.
Revokes every live session for the user. Does NOT clear TOTP enrollment: the second factor is the user’s, not the admin’s.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user_id | path | integer | yes |
Request body (required), application/json, PasswordResetIn
| Field | Type | Required | Description |
|---|---|---|---|
password | string | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
| 404 | user not found |