Users

Users are stored in your database and are represented by a User object within Lucia. By default, they only hold their user id.

const user = {
	userId: "laRZ8RgA34YYcgj"
};

User id#

The primary way to identify users is by their user id. It’s randomly generated by Lucia (a-z and 0-9) and it’s 15 characters long. You can pass a custom user id when creating a user as well.

User attributes#

You can define additional attributes of your users such as email and username.

Defining user attributes#

You can define custom user attributes by returning them in getUserAttributes() configuration. The params for getUserAttributes() will include every field in the user table. See Database for adding custom fields to your user table.

import { lucia } from "lucia";

lucia({
	// ...
	getUserAttributes: (databaseUser) => {
		return {
			username: databaseUser.username
		};
	}
});

const user: User = await auth.getUser(userId);
// `userId` is always defined
const { userId, username } = user;

Create users#

You can create new users by calling Auth.createUser(). This returns the created user.

import { auth } from "./lucia.js";
import { LuciaError } from "lucia";

try {
	const user = await auth.createUser({
		key: {
			providerId,
			providerUserId,
			password
		},
		attributes: {
			username
		} // expects `Lucia.DatabaseUserAttributes`
	});
} catch (e) {
	if (e instanceof LuciaError && e.message === `AUTH_DUPLICATE_KEY_ID`) {
		// key already exists
	}
	// provided user attributes violates database rules (e.g. unique constraint)
	// or unexpected database errors
}

The fields of the attributes property is whatever you defined in Lucia.DatabaseUserAttributes. It should be an empty object with the default configuration (no user attributes defined).

You can optionally create a key alongside the user. This is preferable to creating a key on its own as both the user and key will be created in a single database transaction (if the adapter supports it). It will throw AUTH_DUPLICATE_KEY_ID if the key already exists. To not create a key, pass null:

await auth.createUser({
	key: null
	// ...
});

User attributes errors#

If the user attributes provided violates a database rule (such a unique constraint), Lucia will throw the database/driver/ORM error instead of a regular LuciaError. For example, if you’re using Prisma, Lucia will throw a Prisma error.

Custom user id#

You can use your own user id by passing userId to Auth.createUser().

await auth.createUser({
	userId: generateCustomUserId(),
	attributes: {}
});

Get user#

You can get users by their user id with Auth.getUser().

import { auth } from "./lucia.js";

const user = await auth.getUser(userId);

Update user attributes#

You can update attributes of a user with Auth.updateUserAttributes(). You can update a single field or multiple fields. It returns the updated user, or throws AUTH_INVALID_USER_ID if the user does not exist.

Make sure to invalidate all sessions of the user on password or privilege level change. You can create a new session to prevent the current user from being logged out.

import { auth } from "./lucia.js";
import { LuciaError } from "lucia";

try {
	const user = await auth.updateUserAttributes(
		userId,
		{
			username: newUsername
		} // expects partial `Lucia.DatabaseUserAttributes`
	);
} catch (e) {
	if (e instanceof LuciaError && e.message === `AUTH_INVALID_USER_ID`) {
		// invalid user id
	}
	// provided user attributes violates database rules (e.g. unique constraint)
	// or unexpected database errors
}

const user = await auth.updateUserAttributes(userId, {
	role: "admin" // new privileges
});
await auth.invalidateAllUserSessions(user.userId); // invalidate all user sessions => logout all sessions
const session = await auth.createSession({
	userId: user.userId,
	attributes: {}
}); // new session
// store new session

If you’re using AuthRequest to validate sessions, use AuthRequest.invalidate() to get the latest user data when you next call AuthRequest.validate() and AuthRequest.validateBearerToken().

await auth.updateUserAttributes(userId, {
	username: newUsername
});
authRequest.invalidate();

// returns latest user data
const session = await authRequest.validate();

Delete users#

You can delete users with Auth.deleteUser(). All sessions and keys of the user will be deleted as well. This method will succeed regardless of the validity of the user id.

import { auth } from "./lucia.js";

await auth.deleteUser(userId);

Configuration#

You can configure users in a few ways:

• User attributes with getUserAttributes()