🛣️ Authentication routes
Routes are SDK composers, not Express middleware. Use the common-task map to choose an endpoint and authService to mount the supported API. Try the Bearer workflow before reading individual routes; each route below links its schema and feature so request validation and composition remain visible.
Inventory
View shared source context
import {ok} from 'neverthrow';
import {identity as noop, pick, tap} from 'ramda';
import {
assertDoesNotMatch,
assertIdentityExists,
assertMatches,
assertValidOneTimeTokenExists,
AuthenticationBadRequestError,
AuthenticationConflictError,
AuthenticationForbiddenError,
AuthenticationInvalidInputError,
AuthenticationInvalidTokenError,
AuthenticationNotFoundError,
AuthenticationUnauthorizedError,
AuthenticationUnexpectedDBError,
AuthenticationUnexpectedDbError,
AuthenticationUnexpectedError,
AuthenticationUnprocessableEntityError,
buildTokenVerification,
buildUpdateIdentityActivatedPayload,
buildUpdateIdentityDeactivatedPayload,
buildUpdateIdentityEmailAndEmailVerifiedPayload,
buildUpdateIdentityPasswordPayload,
checkEmailIsUniqueInIdentities,
checkOneTimeToken,
checkToken as checkTokenBlock,
compareStringAgainstHash,
createMfaCode,
createMfaToken,
extractTokenFromAuthorizationHeader,
generateOneTimeToken,
getChangeEmailTokenTarget,
getFingerprint,
getIdentityIdByEmail,
getMfaChallengeTokenTarget,
getResetPasswordTokenTarget,
hash,
invalidateOneTimeToken,
isEmail,
isEmailVerified,
MfaInvalidCodeError,
MfaUnexpectedError,
normalizeBearerLoginResponse,
normalizeBearerRefreshResponse,
normalizeCookieLoginResponse,
sendEmail,
sendMfaCode,
softDeleteRefreshTokens,
storeOneTimeToken,
verifyMfaCode,
} from '../blocks/authentication';
import {normalizeEmptyBody} from '../blocks/common';
import {getIdentityById, updateIdentity} from '../blocks/identity';
import {
buildAcceptInvitationPayload,
buildCheckConfirmEmailTokenPayload,
buildCheckInvitationTokenPayload,
checkToken,
confirmEmail,
confirmEmailTerminator,
createAccessToken,
createRefreshToken,
generateOnetimeToken,
getInvitationById,
getInvitationIdFromTokenInfo,
invalidateOnetimeToken,
isPendingInvitation,
loginWithCredentials,
loginWithOnetimeToken,
logout,
logoutTerminator,
refreshToken,
registerCredentials,
registerTerminator,
restoreOnetimeToken,
sendVerificationEmail,
sendVerificationEmailTerminator,
setResponseCookie,
updateInvitation,
} from '../handlers';
import {
applyPayloadArgs,
compose,
flatMapAsync,
ifElse,
lift,
mapMatchingErrorToFalse,
match,
orThrow,
RouteHandlerPayload,
withLogging,
withRoute,
} from '../primitives';
import {whenCookieAuth} from '../utils/cookie';
import {checkIdentityType, isAuthenticated, isSelf, some} from '../validators';
Details
registerCredentialsRoute
Implementation
Endpoint: POST /auth/register
Register a credential identity.
Access: Public.
Request: registerCredentialsSchema validates the JSON credentials and optional invitation token.
Pipeline: Invitation-token requests run the Invitation handlers around checkToken and registerCredentials; ordinary requests run registerCredentials directly, then registerTerminator.
Success: 201 with {email, id}.
Failure: 400 missing/failed input, 401 invalid invitation token, 404 missing invitation, 422 duplicate identity, or 500 persistence failure.View complete source
loginWithCredentialsRoute
Implementation
Endpoint: POST /auth/login
Sign in with credentials; may initiate MFA.
Access: Public.
Request: loginWithCredentialsSchema validates the JSON email, password, and optional fingerprint.
Pipeline: loginWithCredentials; the MFA branch creates/sends a challenge, while the session branch runs createAccessToken, createRefreshToken, optional setResponseCookie, and a mode-specific normalizer.
Success: 200 with an MFA token, cookie-mode {id} plus cookies, or Bearer {accessToken, id, refreshToken}.
Failure: 401 for locked/wrong credentials; MFA failures are 400 or 500.View complete source
resendMfaCodeRoute
Implementation
Endpoint: POST /auth/mfa/resend
Issue a replacement MFA challenge.
Access: Public to a caller holding a valid MFA challenge token.
Request: resendMfaCodeSchema validates the token and optional fingerprint.
Pipeline: getFingerprint, getMfaChallengeTokenTarget, checkToken, createMfaCode, createMfaToken, sendMfaCode, then response selection.
Success: 200 with the replacement challenge token.
Failure: 400 invalid token/code input, 401 failed token validation, or 500 token/database/mail failure.View complete source
verifyMfaCodeRoute
Implementation
Endpoint: POST /auth/mfa/verify
Verify an MFA challenge.
Access: Public to a caller holding the challenge token and code.
Request: verifyMfaCodeSchema validates token, code, and fingerprint.
Pipeline: Target/fingerprint/token checks, token invalidation, verifyMfaCode, identity lookup, createAccessToken, createRefreshToken, optional setResponseCookie, then a mode-specific normalizer.
Success: 200 with cookie-mode {id} plus cookies or Bearer session tokens.
Failure: 400 invalid code/input, 401 invalid token, 403 invalidated token, 404 missing identity, or 500 persistence/session failure.View complete source
logoutRoute
Implementation
Endpoint: POST /auth/logout
Revoke the current session.
Access: Authenticated through isAuthenticated().
Request: Mode-selected logoutCookieSchema or logoutBearerSchema.
Pipeline: logout, then logoutTerminator.
Success: 204; cookies are cleared and a valid presented refresh record is revoked.
Failure: Authentication failure, 401 identity mismatch, or 500 revocation failure.View complete source
refreshTokenRoute
Implementation
Endpoint: POST /auth/token/refresh
Rotate an access/refresh token pair.
Access: Possession of a valid refresh token; there is no route validator.
Request: refreshTokenCookieSchema reads the cookie transport; refreshTokenBearerSchema requires the body token.
Pipeline: refreshToken, optional setResponseCookie, then cookie empty-body or Bearer token normalization.
Success: Cookie mode returns 204 and rotated cookies; Bearer mode returns 200 with {accessToken, refreshToken}.
Failure: 401 invalid/reused token, 422 missing token, 400 failed revocation, or 500 persistence failure.View complete source
checkTokenRoute
Implementation
Endpoint: POST /auth/token/check
Validate an access or one-time token.
Access: Public; validity is established from the body token.
Request: checkTokenSchema validates token and optional target.
Pipeline: checkToken (the block, not the handler), then orThrow.
Success: 200 with the validated tokenInfo; a valid one-time token is consumed.
Failure: 400 invalid/security-check-failing token, 401 failed validation, or 500 one-time-token database failure.View complete source
deleteRefreshTokensRoute
Implementation
Endpoint: DELETE /auth/:identityId/refresh-tokens
Revoke an identity refresh-token records.
Access: Authenticated administrator or matching identity.
Request: deleteRefreshTokensSchema validates the identityId path parameter.
Pipeline: softDeleteRefreshTokens, empty-body normalization, then orThrow.
Success: 204, including when no active refresh records match.
Failure: Authentication/authorization failure or 500 database failure.View complete source
loginWithOnetimeTokenRoute
Implementation
Endpoint: POST /auth/ott/login
Complete passwordless login.
Access: Public to a caller holding an active login-target one-time token.
Request: loginWithOnetimeTokenSchema validates the body token and fingerprint.
Pipeline: loginWithOnetimeToken, token invalidation, createAccessToken, createRefreshToken, optional setResponseCookie, then mode-specific normalization.
Success: 200 with cookie-mode {id} plus cookies or a Bearer session body.
Failure: 401 verification failure, 403 wrong/invalid token, 404 missing identity, or session-generation failure.View complete source
generateOnetimeTokenRoute
Implementation
Endpoint: POST /auth/ott/generate
Generate a one-time token for a custom flow.
Access: Authenticated administrator.
Request: No schema is composed; runtime expects JSON tokenData as an object and accepts target and fingerprint.
Pipeline: generateOnetimeToken.
Success: Default 200 with the handler’s successful Result<RouteHandlerPayload>; this legacy route has no terminator and is not mounted by authService.
Failure: 400 invalid data/insert result or 500 generation/database failure.View complete source
restoreOnetimeTokenRoute
Implementation
Endpoint: POST /auth/ott/restore
Restore an invalidated one-time token.
Access: Authenticated administrator.
Request: No schema is composed; runtime reads body token.
Pipeline: restoreOnetimeToken.
Success: Default 200 with the handler’s successful Result<RouteHandlerPayload>; zero matching records still succeed.
Failure: 401 undecodable token, 422 non-stateful token, or 500 update failure.View complete source
invalidateOnetimeTokenRoute
Implementation
Endpoint: POST /auth/ott/invalidate
Invalidate a one-time token.
Access: Authenticated administrator.
Request: No schema is composed; runtime reads token and fingerprint from pipeline context or body.
Pipeline: invalidateOnetimeToken.
Success: Default 200 with the handler’s successful Result<RouteHandlerPayload>; zero matching records still succeed.
Failure: 422 missing/invalid/non-stateful input or 500 update failure.View complete source
sendVerificationEmailRoute
Implementation
Endpoint: POST /auth/:identityId/send-verification-email
Send a verification email.
Access: Authenticated administrator or matching identity.
Request: sendVerificationEmailSchema validates the identity path and an optional body fingerprint.
Pipeline: sendVerificationEmail, then sendVerificationEmailTerminator.
Success: 204 after token storage and successful mail delivery.
Failure: 400 disabled/missing configuration or email, 404 missing identity, 501 token generation failure, or 500 storage/mail failure.View complete source
confirmEmailRoute
Implementation
Endpoint: POST /auth/confirm-email
Confirm an email-verification token.
Access: Public to a caller holding the confirmation token.
Request: confirmEmailSchema validates the body token.
Pipeline: buildCheckConfirmEmailTokenPayload, handler checkToken, confirmEmail, then confirmEmailTerminator.
Success: 204; the stored token is consumed and the identity becomes verified.
Failure: 400 invalid token, 401 failed validation, 403 bad token data, 404 missing identity, 409 already verified, or 500 persistence failure.View complete source
changeEmailRoute
Implementation
Endpoint: PATCH /auth/:identityId/change-email
Start an email-change flow.
Access: Authenticated administrator or matching identity.
Request: changeEmailSchema validates the path identity and new email.
Pipeline: Identity/uniqueness checks, target and request-security construction, token generation/storage, sendEmail, empty-body normalization, then orThrow.
Success: 204 after the confirmation token is mailed.
Failure: Mapped Authentication errors from 400 through 500, including 404 identity, 409 email conflict, and 422 fingerprint format.View complete source
confirmNewEmailRoute
Implementation
Endpoint: POST /auth/confirm-new-email
Confirm a new email address.
Access: Public to a caller holding the change-email token.
Request: confirmNewEmailSchema validates token and fingerprint.
Pipeline: Token target/security checks, one-time-token validation and invalidation, email uniqueness/format checks, identity update, empty-body normalization, then orThrow.
Success: 204.
Failure: Mapped Authentication errors from 400 through 500, notably 401 verification, 403 inactive token, 409 email conflict, and 404 identity.View complete source
sendResetPasswordLinkEmailRoute
Implementation
Endpoint: POST /auth/send-reset-password-link-email
Send a password-reset link.
Access: Public.
Request: sendResetPasswordLinkEmailSchema validates the email and request-security headers.
Pipeline: Identity lookup, reset target/fingerprint/security construction, token generation/storage, sendEmail, empty-body normalization, then orThrow.
Success: 204.
Failure: Mapped Authentication errors including 404 unknown email, 422 malformed fingerprint, and 500 generation/storage/mail failure.View complete source
completePasswordResetRoute
Implementation
Endpoint: POST /auth/reset-password
Complete password reset with a token.
Access: Public to a caller holding a valid reset token.
Request: completePasswordResetSchema validates the replacement password. Runtime also reads the reset token from the Authorization header, but that source parameter is currently commented out of the schema.
Pipeline: Token extraction/checks, identity and password comparisons, token invalidation, password hashing/update, notification email, empty-body normalization, then orThrow.
Success: 204.
Failure: Mapped Authentication errors from 400 through 500, including 401 token failure, 403 inactive token, and 404 identity.View complete source
changePasswordRoute
Implementation
Endpoint: PATCH /auth/:identityId/change-password
Change an authenticated identity password.
Access: Authenticated administrator or matching identity.
Request: changePasswordSchema validates path ID and current/replacement passwords.
Pipeline: Identity lookup, current/new password comparisons, hashing/update, refresh-token revocation, sendEmail, empty-body normalization, then orThrow.
Success: 204.
Failure: Mapped Authentication errors from 400 through 500, including invalid current/reused password and missing identity.View complete source
deactivateRoute
Implementation
Endpoint: POST /auth/deactivate
Deactivate an identity.
Access: Authenticated administrator or the body identityId.
Request: deactivateSchema validates the JSON identity ID.
Pipeline: Identity lookup and verified-email guard, deactivation update, refresh-token revocation, mode-selected access-token validation, conditional email, empty-body normalization, then orThrow.
Success: 204.
Failure: Authentication/authorization failure or mapped Authentication errors from 400 through 500.View complete source
activateRoute
Implementation
Endpoint: POST /auth/activate
Reactivate an identity.
Access: Authenticated administrator.
Request: activateSchema validates the JSON identity ID.
Pipeline: Identity lookup, verified-email guard, activation update, empty-body normalization, then orThrow.
Success: 204.
Failure: Authentication/administrator failure or mapped Authentication errors from 400 through 500.View complete source