Sign in and sign out
Run integrated Better Auth operations and handle their identity lifecycle.
useConvexAuth().client is the Better Auth client. The module wraps it, so the Convex client follows every session change that the client makes.
client is always present. Call its methods from browser event handlers. During server rendering, a method call throws a ConvexCallError with code CLIENT_UNAVAILABLE. For GitHub and Google, see Social sign-in.
Email and password sign-in
Password sign-in is off until you name it. Pass an object to turn it on:
export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
emailAndPassword: {},
email: sendAuthEmail,
})With emailAndPassword: {}, a person must verify the address before sign-in
(requireEmailVerification is true), a password reset ends every other
session (revokeSessionsOnPasswordReset is true), and a password change ends
the other sessions. Pass requireEmailVerification: false only when your app
has no mail provider and never decides access by email. sendAuthEmail is
your email hook. See
Transactional auth email.
const { client } = useConvexAuth()
const signingIn = ref(false)
async function signIn() {
signingIn.value = true
try {
const result = await client.signIn.email({
email: email.value,
password: password.value,
})
if (result.error) formError.value = 'Sign in could not be completed'
} finally {
signingIn.value = false
}
}The call returns after Convex accepts the new session, so signingIn covers the whole sign-in. Disable the submit button while it is true.
Do not display raw credential errors if they reveal whether an account exists.
Sign-up
const { client } = useConvexAuth()
const result = await client.signUp.email({
name: name.value,
email: email.value,
password: password.value,
})Sign-up does not sign the user in, because createBetterConvexAuth always sets autoSignIn: false. By default the user must verify the email address before the first sign-in, so tell the person to check their email. With requireEmailVerification: false the user can sign in right away with any address, verified or not. Passwords need at least 15 characters.
Password sign-in and access by email
Anyone can start a password sign-up for an address they do not own. When the
real owner later proves the address, the library ends every session that
existed before the proof, but it cannot tell the owner from a victim who opens
the verification mail of a stranger's sign-up. The password of that first
sign-up survives. So an app that decides access by email (invitations, allow
lists, company domains) should sign people in with email codes (emailOTP)
instead of passwords. If you keep passwords, check emailVerified when you
decide access and accept that residual risk. Write the verification mail so it
says: "If you did not create an account, ignore this email."
Email code sign-in
Turn on emailOTP: {} (a deployment needs the email hook; locally, codes go to the dev outbox in the convex dev log) and add emailOTPClient() to
the client definition.
const { client } = useConvexAuth()
await client.emailOtp.sendVerificationOtp({ email: email.value, type: 'sign-in' })
// Show a code field, then:
const result = await client.signIn.emailOtp({ email: email.value, otp: code.value })
if (result.error) formError.value = 'Sign in could not be completed'A code proves the address, so a person who signs in this way replaces any password or session an earlier sign-up left on that address. Codes are stored hashed.
To let people sign in with one tap from the email, put the code in a link. See Sign-in link.
Sign-out
const { client } = useConvexAuth()
await client.signOut()
await navigateTo('/')Your application decides where to navigate. The module orders the session operations, clears the previous user's query data, and replaces the Convex client.
Do not call clearNuxtState() without keys during sign-out. On Nuxt 5 it resets the module's convex:* state to its initial value. The auth state then shows as pending, nothing loads it again, and protected routes wait until their timeout and then treat the visitor as signed out. Pass the keys of your own state, for example clearNuxtState(['cart']).
Wait for the auth state
Queries already wait for auth. Use ready() only when other code must wait until the first auth state is known:
const status = await useConvexAuth().ready({ timeoutMs: 5_000 })Do not call ready() before every query.
Pending work and auth status
pending can be true while status stays authenticated. Keep the signed-in UI visible during a background refresh.
Failures across identity changes
A mutation, action, or useConvex() call that is still running when the user changes rejects with IDENTITY_CHANGED. Do not show its result to the new user. Do not retry a write automatically, because it may already have succeeded.