REST: Auth
Sessions and credentials. Generated from mnema-talk v3.3.13 (cca4f0fdb723).
Confirm an e-mail address
POST /api/auth/email/verify
Uses the single-use token from the confirmation mail (no session needed; the link carries it in the URL fragment). The token works once, for 24 hours, and only while the account still has the address it was sent to. Every unusable token answers the same 400.
Authentication: none
Request body (application/json, required): VerifyEmailRequest
| Field | Type | Description |
|---|---|---|
token (required) | string | Token is the one from the link in the confirmation mail. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Address confirmed. | |
| 400 | INVALID_INPUT: the link is invalid or has expired. | ErrorResponse |
| 409 | CONFLICT: another account has already confirmed this address. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Sign in
POST /api/auth/login
Sets the session cookie and a signed known-device cookie. Rate limited per IP (60 per 15 min, IPv6 per /64) and by escalating lockouts per address+username. Once the account-wide guess cap trips, devices without the known-device cookie get about one password check per minute per client address (and about ten per minute for the whole account); everything else is answered 429 without a check. The cap lasts at most 15 minutes. Limited requests answer 429 with Retry-After.
Authentication: none
Request body (application/json, required): LoginRequest
| Field | Type | Description |
|---|---|---|
password (required) | string (password) | |
username (required) | string | Username is case-insensitive. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Signed in. | UserEnvelope |
| 202 | Correct password, but the account has two-factor sign-in: finish with POST /api/auth/login/2fa. No session is set yet. | TwoFactorChallenge |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | INVALID_CREDENTIALS: unknown user or wrong password. | ErrorResponse |
| 403 | ACCOUNT_DISABLED (correct password, disabled account) or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: too many password checks are queued; retry after the Retry-After seconds. | ErrorResponse |
UserEnvelope
| Field | Type | Description |
|---|---|---|
user (required) | User |
Finish a sign-in with the second factor
POST /api/auth/login/2fa
Second step of POST /api/auth/login for an account with two-factor sign-in: the challenge from the 202 answer plus a six-digit authenticator code or an unused recovery code. Sets the session cookie like a normal sign-in. The challenge lives five minutes, is bound to that sign-in, and accepts five codes in total; an authenticator code works once (a replay is refused). After ten wrong authenticator codes the authenticator step of the account is locked (429, escalating, at most 15 minutes); recovery codes are limited separately, per client, so that lockout never blocks them. Wrong, expired, replayed and unknown all answer the same 401; sessions revoked since the password check also fail.
Authentication: none
Request body (application/json, required): TwoFactorLoginRequest
| Field | Type | Description |
|---|---|---|
challenge (required) | string | |
code (required) | string | Code is the six digits of the authenticator app, or an unused recovery code (spaces and dashes are ignored). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Signed in; security_notice is set once when wrong codes were entered since the last sign-in. | TwoFactorLoginResult |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | INVALID_CREDENTIALS: the code or the challenge is not valid. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the account's second step is locked. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
TwoFactorLoginResult
| Field | Type | Description |
|---|---|---|
security_notice | SecurityNotice | SecurityNotice is set once when at least five wrong codes were entered since the last sign-in. |
user (required) | User |
Sign out
POST /api/auth/logout
Clears the session cookie and revokes this session, so a copied cookie stops working, and closes the WebSockets opened with it. Needs no session.
Authentication: none
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Cookie cleared. | |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Sign out everywhere
POST /api/auth/logout-all
Invalidates every session of the caller, including copied cookies, and closes their open WebSockets.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | All sessions revoked. | |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Current user
GET /api/auth/me
The signed-in account: profile, chosen presence and language, and whether the community rules still have to be accepted (rules_pending). The web app calls it on every start to learn whether its session is still valid.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The caller, including chosen presence. | User |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | 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. |
Sign-in options
GET /api/auth/options
Which recovery paths the server offers, so the sign-in screen can show them. Carries nothing about any account.
Authentication: none
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Options. | AuthOptions |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
AuthOptions
| Field | Type | Description |
|---|---|---|
community_icon | string | CommunityIcon is the version of the community icon (GET /api/community/icon), left out while the Owner set none. Public as well. |
community_name | string | CommunityName is what the sign-in screen calls the community: the Owner's name for it, else the host. Public, like the rest of this answer. |
password_reset (required) | boolean | PasswordReset is true when members can reset a forgotten password by e-mail (the server can send mail). It does not say who has an address. |
Change own password
PUT /api/auth/password
Signs out all other sessions and keeps the current one (a fresh cookie is set); open WebSockets are closed and reconnect with it. Needs the current password and, while two-factor sign-in is on, a current code. Five wrong current passwords trigger a lockout (429).
Authentication: Session cookie
Request body (application/json, required): ChangePasswordRequest
| Field | Type | Description |
|---|---|---|
code | string | Code is a current authenticator code or an unused recovery code; needed only while two-factor sign-in is on. |
current_password (required) | string (password) | |
new_password (required) | string (password) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Password changed. | |
| 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: current password or code is incorrect, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the second step is locked. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Set a new password with a reset link
POST /api/auth/password-reset/confirm
Uses the single-use token from the reset mail. The token works once and for 30 minutes. A new password follows the usual policy (the Owner needs 14 characters). Success ends every session of the account, including other devices; it does not sign anyone in, and a second factor, if enabled, is still asked at sign-in. Every unusable token answers the same 400.
Authentication: none
Request body (application/json, required): PasswordResetConfirmation
| Field | Type | Description |
|---|---|---|
new_password (required) | string (password) | |
token (required) | string | Token is the one from the link in the reset mail. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Password changed. | |
| 400 | INVALID_INPUT: the link is invalid or has expired, or the password does not meet the policy. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: too many password checks are queued; retry after the Retry-After seconds. | ErrorResponse |
Ask for a password reset mail
POST /api/auth/password-reset/request
Answers 202 with an empty body whether or not the address belongs to an account, has been confirmed, or the account is disabled, and takes the same time either way: lookup and mail run after the response. Only an active account with a confirmed address gets a single-use link (valid 30 minutes). Rate limited per client address (10 per hour, IPv6 per /64) and, silently, per address and per account (a few mails per hour); 404 when the server cannot send mail.
Authentication: none
Request body (application/json, required): PasswordResetRequest
| Field | Type | Description |
|---|---|---|
email (required) | string (email) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 202 | Accepted; if the address is confirmed for an account, a mail is on its way. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON or not an e-mail address. | ErrorResponse |
| 404 | NOT_FOUND: the server cannot send e-mail. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Register with an invite code
POST /api/auth/register
Creates a regular user, consumes one use of the invite and signs the user in. Rate limited per IP (10 per hour).
Authentication: none
Request body (application/json, required): RegisterRequest
| Field | Type | Description |
|---|---|---|
display_name | string | DisplayName defaults to the username. |
invite_code (required) | string | |
password (required) | string (password) | Password needs 10 characters at least and 72 bytes at most. |
username (required) | string | Username: 2-32 characters, lowercase letters, digits, '' and '.', no leading, trailing or repeated '.'. Spaces become '' and capitals lower-case before checking. Unique regardless of case; "all" and "here" are reserved. Accounts created before this rule keep their names. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Account created and signed in. | UserEnvelope |
| 400 | INVALID_INPUT: validation failed, or the invite code is invalid, expired or used up. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 409 | CONFLICT: the resource already exists. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: too many password checks are queued; retry after the Retry-After seconds. | ErrorResponse |
UserEnvelope
| Field | Type | Description |
|---|---|---|
user (required) | User |
List my sessions
GET /api/auth/sessions
The caller's own sessions on this server, most recently active first: a coarse device label, when each was created and last used, whether it is the one making this request and whether its device receives push notifications. Sessions of other members are never listed.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Sessions. | MemberSessionList |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
MemberSessionList
| Field | Type | Description |
|---|---|---|
sessions (required) | MemberSession[] |
Sign out all my other sessions
POST /api/auth/sessions/revoke-others
Ends every session of the caller except the one making the request, and removes their push subscriptions. A session that has not made a request since the 1.2 upgrade is not listed yet and is not covered; "Sign out everywhere" (POST /api/auth/logout-all) ends those too.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | How many sessions ended. | RevokedSessions |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
RevokedSessions
| Field | Type | Description |
|---|---|---|
revoked (required) | integer |
Sign out one of my sessions
DELETE /api/auth/sessions/{id}
Ends one of the caller's own sessions and removes its push subscriptions; its open WebSockets are closed. Signing out the session the request was made with is allowed and clears the cookie. A session that belongs to someone else answers 404 like one that does not exist.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Session ID from the list. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Session ended. | |
| 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: 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 |
Preview an invite
GET /api/invites/{code}
Public, no session. Says whether an invite code can still be used and, if so, the community's name, when the code expires and the channel it lands the new member in (only one every new member can see). Unknown, weak legacy custom, expired, revoked and used-up codes all answer the same {"valid": false}; nothing else about the invite is revealed. Rate limited per IP (30 per minute, IPv6 per /64)
Authentication: none
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | path | string | yes | Invite code. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Preview. | InvitePreview |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
InvitePreview
| Field | Type | Description |
|---|---|---|
channel_id | string (uuid) | ChannelID is the channel the invite lands the new member in. It is left out for an invite without one, and for a channel that a plain new member could not see: they land in the default channel then. |
community_name | string | |
expires_at | string (date-time) | |
valid (required) | boolean |
Preview a vanity invite link
GET /api/join/{slug}
Public, no session. Says whether the vanity link /join/{slug} exists and, if so, the community's name and whether it accepts sign-ups. When it does, register with invite_code "~{slug}"; when it does not, the visitor signs in or needs an individual invite code. Unknown slugs answer {"valid": false}. Rate limited per IP like the invite preview (30 per minute, IPv6 per /64).
Authentication: none
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | Link name. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Preview. | JoinPreview |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
JoinPreview
| Field | Type | Description |
|---|---|---|
accepts_signups | boolean | AcceptsSignups: the link is a permanent public invite, and the sign-up names the slug as "~ |
community_name | string | |
valid (required) | boolean |