Skip to main content
The usernamePassword plugin lets users pick a username at registration and sign in with it. It is a drop-in alternative to the email-password plugin for apps where email addresses are not the primary identity.

Setup

lib/kavach.ts
Mount the handler the same way as any other plugin, see adapters.

Sign up

POST /auth/sign-up
Sign up (client)
Error codes

Sign in

POST /auth/sign-in
Sign in (client)
Returns 401 with code INVALID_CREDENTIALS for any bad username/password combination. The response never reveals whether the username exists.

Change username

POST /auth/change-username Requires an active session. Usernames must still be unique after the change.
Change username (client)

Configuration reference

number
default:3
Minimum username length.
number
default:32
Maximum username length.
RegExp
default:"/^[a-z0-9_-]+$/i"
Regex that the username must match. Applied after length validation.
boolean
default:"false"
Whether usernames are case-sensitive during lookup.
Last modified on April 29, 2026