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

FieldTypeDescription
token (required)stringToken is the one from the link in the confirmation mail.

Responses

StatusMeaningBody
204Address confirmed.
400INVALID_INPUT: the link is invalid or has expired.ErrorResponse
409CONFLICT: another account has already confirmed this address.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

FieldTypeDescription
password (required)string (password)
username (required)stringUsername is case-insensitive.

Responses

StatusMeaningBody
200Signed in.UserEnvelope
202Correct password, but the account has two-factor sign-in: finish with POST /api/auth/login/2fa. No session is set yet.TwoFactorChallenge
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401INVALID_CREDENTIALS: unknown user or wrong password.ErrorResponse
403ACCOUNT_DISABLED (correct password, disabled account) or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: too many password checks are queued; retry after the Retry-After seconds.ErrorResponse
UserEnvelope
FieldTypeDescription
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

FieldTypeDescription
challenge (required)string
code (required)stringCode is the six digits of the authenticator app, or an unused recovery code (spaces and dashes are ignored).

Responses

StatusMeaningBody
200Signed in; security_notice is set once when wrong codes were entered since the last sign-in.TwoFactorLoginResult
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401INVALID_CREDENTIALS: the code or the challenge is not valid.ErrorResponse
429RATE_LIMITED: too many requests, or the account's second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
TwoFactorLoginResult
FieldTypeDescription
security_noticeSecurityNoticeSecurityNotice 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

StatusMeaningBody
204Cookie cleared.
403FORBIDDEN: cross-origin request rejected by the CSRF check.ErrorResponse
500INTERNAL_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

StatusMeaningBody
204All sessions revoked.
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: cross-origin request rejected by the CSRF check.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

StatusMeaningBody
200The caller, including chosen presence.User
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.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.

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

StatusMeaningBody
200Options.AuthOptions
429RATE_LIMITED: too many requests.ErrorResponse
AuthOptions
FieldTypeDescription
community_iconstringCommunityIcon is the version of the community icon (GET /api/community/icon), left out while the Owner set none. Public as well.
community_namestringCommunityName 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)booleanPasswordReset 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

FieldTypeDescription
codestringCode 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

StatusMeaningBody
204Password changed.
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: current password or code is incorrect, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests, or the second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

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

FieldTypeDescription
new_password (required)string (password)
token (required)stringToken is the one from the link in the reset mail.

Responses

StatusMeaningBody
204Password changed.
400INVALID_INPUT: the link is invalid or has expired, or the password does not meet the policy.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: 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

FieldTypeDescription
email (required)string (email)

Responses

StatusMeaningBody
202Accepted; if the address is confirmed for an account, a mail is on its way.
400Invalid input (INVALID_INPUT): malformed JSON or not an e-mail address.ErrorResponse
404NOT_FOUND: the server cannot send e-mail.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

FieldTypeDescription
display_namestringDisplayName 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)stringUsername: 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

StatusMeaningBody
201Account created and signed in.UserEnvelope
400INVALID_INPUT: validation failed, or the invite code is invalid, expired or used up.ErrorResponse
403FORBIDDEN: cross-origin request rejected by the CSRF check.ErrorResponse
409CONFLICT: the resource already exists.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: too many password checks are queued; retry after the Retry-After seconds.ErrorResponse
UserEnvelope
FieldTypeDescription
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

StatusMeaningBody
200Sessions.MemberSessionList
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
MemberSessionList
FieldTypeDescription
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

StatusMeaningBody
200How many sessions ended.RevokedSessions
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
RevokedSessions
FieldTypeDescription
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

NameInTypeRequiredDescription
idpathstring (uuid)yesSession ID from the list.

Responses

StatusMeaningBody
204Session ended.
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: 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

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

NameInTypeRequiredDescription
codepathstringyesInvite code.

Responses

StatusMeaningBody
200Preview.InvitePreview
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
InvitePreview
FieldTypeDescription
channel_idstring (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_namestring
expires_atstring (date-time)
valid (required)boolean

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

NameInTypeRequiredDescription
slugpathstringyesLink name.

Responses

StatusMeaningBody
200Preview.JoinPreview
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
JoinPreview
FieldTypeDescription
accepts_signupsbooleanAcceptsSignups: the link is a permanent public invite, and the sign-up names the slug as "~" in invite_code.
community_namestring
valid (required)boolean

Something wrong on this page? Tell us.