REST: Admin, users
Management endpoints. Each operation names the permission it needs: Owner only, a permission such as Manage members, Ban members or Manage channels, or the Administrator permission. Generated from mnema-talk v3.3.13 (cca4f0fdb723).
List all accounts
GET /api/admin/users
Admins first, then by username. Requires the Manage members or Manage roles permission (403 otherwise). Includes each account's role_ids.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Accounts. | AdminUser[] |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage members or Manage roles permission. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Lift a ban
DELETE /api/admin/users/{id}/ban
Lets the member sign in again. A revoked invite stays revoked. Needs Ban members and a higher role than the member.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Ban members permission, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the member does not exist or is not banned. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Ban a member
POST /api/admin/users/{id}/ban
Ends the member's sessions and connections and blocks signing in, with an optional reason and an optional duration (otherwise for good). The account and its messages stay. By default the invite the account registered with is revoked, so that code cannot create the account again; that only happens when the caller also holds Manage invites (or is the Owner), otherwise the ban goes through and the invite stays. Needs Ban members and a higher role than the member; the Owner cannot be banned. Kicking someone without a record is Disable.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Request body (application/json, required): BanRequest
| Field | Type | Description |
|---|---|---|
duration_seconds | integer | null | DurationSeconds ends the ban by itself after that long (60 seconds to ten years); null or missing bans for good. |
reason (required) | string | Reason is shown to the member when they try to sign in; send an empty string for none. |
revoke_invite | boolean | RevokeInvite also revokes the invite the account registered with, so that code cannot create the account anew (default true). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Ban members permission, the member's highest role is not below yours, or the member is the Owner, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Disable an account
POST /api/admin/users/{id}/disable
Signs the user out, drops their live connections and removes them from voice. Requires the Manage members permission (403 otherwise); members whose highest role is not below the caller's, and the Owner, cannot be targeted. The Owner cannot be targeted (400).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Re-enable an account
POST /api/admin/users/{id}/enable
Requires the Manage members permission (403 otherwise); members whose highest role is not below the caller's, and the Owner, cannot be targeted.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Remove a user from voice
POST /api/admin/users/{id}/kick
400 when the user is not in a Talk the caller may moderate (View channels and Disconnect members in that Talk; a Talk they may not moderate answers the same). Requires the Disconnect members permission (403 otherwise); members whose highest role is not below the caller's cannot be targeted, and the Owner cannot be removed (400).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Disconnect members permission, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Clear an account's login lockout
POST /api/admin/users/{id}/login-lockout/clear
Forgets the wrong-password counters and lockouts held in memory for the account (per client address, account-wide and the password-change lockout), so its owner can sign in at once. Owner only (403 otherwise). The same is possible from the host with mnema-talk unlock <username>.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: only the Owner may do this, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Set a user's password
POST /api/admin/users/{id}/password
Ends all of the user's sessions. Owner only (403 otherwise). The Owner must confirm with their own current_password and, while their two-factor sign-in is on, a current code (403 when missing or wrong); wrong answers count toward the usual lockouts.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Request body (application/json, required): SetPasswordRequest
| Field | Type | Description |
|---|---|---|
code | string | Code is a current authenticator code or an unused recovery code; needed only while the Owner has two-factor sign-in on. |
current_password | string (password) | CurrentPassword is the Owner's own password. |
password (required) | string (password) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: only the Owner may do this, the Owner's password or code is missing or wrong, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Generate a temporary password
POST /api/admin/users/{id}/password-reset
Ends all sessions; the password is returned once. Owner only (403 otherwise). The Owner must confirm with their own current_password and, while their two-factor sign-in is on, a current code (403 when missing or wrong); wrong answers count toward the usual lockouts.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Request body (application/json): OwnerProof
| Field | Type | Description |
|---|---|---|
code | string | Code is a current authenticator code or an unused recovery code; needed only while the Owner has two-factor sign-in on. |
current_password | string (password) | CurrentPassword is the Owner's own password. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Temporary password. | TemporaryPassword |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: only the Owner may do this, the Owner's password or code is missing or wrong, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
TemporaryPassword
| Field | Type | Description |
|---|---|---|
password (required) | string | Password is shown once; it is never stored in plain text. |
Revoke all sessions of a user
POST /api/admin/users/{id}/sessions/revoke
Requires the Manage members permission (403 otherwise); members whose highest role is not below the caller's, and the Owner, cannot be targeted.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Edit or clear a member's status line
PUT /api/admin/users/{id}/status
Broadcasts user_update. Requires the Manage members permission (403 otherwise); members whose highest role is not below the caller's, and the Owner, cannot be targeted.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Request body (application/json, required): SetStatusRequest
| Field | Type | Description |
|---|---|---|
expires_at | string (date-time) | ExpiresAt makes the status clear itself at this absolute time (the client computes it from the member's time zone). Omitted or null: it stays until changed. Must lie in the future, at most a year ahead; ignored when the status is cleared and when an admin sets another member's status. |
status_text (required) | string | StatusText: empty clears the status. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user (public view unless it is the caller). | User |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes). |
bio (required) | string | |
created_at (required) | string (date-time) | |
display_name (required) | string | |
id (required) | string (uuid) | |
locale (required) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions). |
rules_pending | boolean | RulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account. |
status_expires_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent. |
End a member's timeout
DELETE /api/admin/users/{id}/timeout
Lifts a running timeout at once. Needs Timeout members and a higher role than the member. The member is told through a moderation_notice event.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Timeout members permission, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Time out a member
POST /api/admin/users/{id}/timeout
Silences a member for a while: they can read but not post, react, speak, share video or join Talks, and are removed from the Talk they are in. It ends by itself. Needs Timeout members and a higher role than the member; the Owner cannot be timed out, nobody can time themselves out. The member is told through a moderation_notice event. Replaces a running timeout.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Request body (application/json, required): TimeoutRequest
| Field | Type | Description |
|---|---|---|
duration_seconds (required) | integer | DurationSeconds is how long the member is silenced, from now. |
reason | string | Reason is shown to the member. Optional. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The timeout. | TimeoutState |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Timeout members permission, the member's highest role is not below yours, or the member is the Owner or yourself, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
TimeoutState
| Field | Type | Description |
|---|---|---|
reason (required) | string | |
timeout_until (required) | string (date-time) | TimeoutUntil is when it ends. |
user_id (required) | string (uuid) |
Reset a member's two-factor sign-in
POST /api/admin/users/{id}/two-factor/reset
For a member who lost the authenticator and the recovery codes: turns two-factor sign-in off, deletes the secret and recovery codes and ends all sessions of the account. Owner only (403 otherwise); the Owner account cannot be targeted (400), its second factor is reset from the host with mnema-talk reset-2fa <username>.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Request body (application/json): OwnerProof
| Field | Type | Description |
|---|---|---|
code | string | Code is a current authenticator code or an unused recovery code; needed only while the Owner has two-factor sign-in on. |
current_password | string (password) | CurrentPassword is the Owner's own password. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: only the Owner may do this, the Owner's password or code is missing or wrong, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |