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

StatusMeaningBody
200Accounts.AdminUser[]
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage members or Manage roles permission.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Ban members permission, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the member does not exist or is not banned.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json, required): BanRequest

FieldTypeDescription
duration_secondsinteger | nullDurationSeconds ends the ban by itself after that long (60 seconds to ten years); null or missing bans for good.
reason (required)stringReason is shown to the member when they try to sign in; send an empty string for none.
revoke_invitebooleanRevokeInvite also revokes the invite the account registered with, so that code cannot create the account anew (default true).

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: 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
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Disconnect members permission, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json, required): SetPasswordRequest

FieldTypeDescription
codestringCode is a current authenticator code or an unused recovery code; needed only while the Owner has two-factor sign-in on.
current_passwordstring (password)CurrentPassword is the Owner's own password.
password (required)string (password)

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, the Owner's password or code is missing or wrong, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json): OwnerProof

FieldTypeDescription
codestringCode is a current authenticator code or an unused recovery code; needed only while the Owner has two-factor sign-in on.
current_passwordstring (password)CurrentPassword is the Owner's own password.

Responses

StatusMeaningBody
200Temporary password.TemporaryPassword
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, the Owner's password or code is missing or wrong, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
TemporaryPassword
FieldTypeDescription
password (required)stringPassword 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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json, required): SetStatusRequest

FieldTypeDescription
expires_atstring (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)stringStatusText: empty clears the status.

Responses

StatusMeaningBody
200Updated user (public view unless it is the caller).User
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage members permission, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL 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)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole 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_pendingbooleanRulesPending 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_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity 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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Timeout members permission, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json, required): TimeoutRequest

FieldTypeDescription
duration_seconds (required)integerDurationSeconds is how long the member is silenced, from now.
reasonstringReason is shown to the member. Optional.

Responses

StatusMeaningBody
200The timeout.TimeoutState
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: 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
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
TimeoutState
FieldTypeDescription
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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json): OwnerProof

FieldTypeDescription
codestringCode is a current authenticator code or an unused recovery code; needed only while the Owner has two-factor sign-in on.
current_passwordstring (password)CurrentPassword is the Owner's own password.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, the Owner's password or code is missing or wrong, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Something wrong on this page? Tell us.