User & Accounts

Beyond authenticating users, Better Auth also provides a set of methods to manage users. This includes, updating user information, changing passwords, and more.

User table

The user table stores the user data. The user table has the following fields:

• id: The user id.
• email: The email of the user.
• name: The name of the user.
• image: The image of the user.
• createdAt: The creation date of the user.
• updatedAt: The last update date of the user.

The user table can be extended by plugins to store additional data. When a plugin extends a user table it's infered by the type system and can be used in the client.

Update User

Update User Information

To update user information, you can use the updateUser function provided by the client. The updateUser function takes an object with the following properties:

await authClient.user.update({
    image: "https://example.com/image.jpg",
    name: "John Doe",
})

Change Email

To allow users to change their email, first enable the changeEmail feature, which is disabled by default. Set changeEmail.enabled to true:

export const auth = betterAuth({
    user: {
        changeEmail: {
            enabled: true,
        }
    }
})

For users with a verified email, provide the sendChangeEmailVerification function. This function triggers when a user changes their email, sending a verification email with a URL and token. If the current email isn't verified, the change happens immediately without verification.

export const auth = betterAuth({
    user: {
        changeEmail: {
            enabled: true,
            sendChangeEmailVerification: async (user, newEmail, url, token) => {
                await sendEmail({
                    to: newEmail,
                    subject: 'Verify your email change',
                    text: `Click the link to verify: ${url}`
                })
            }
        }
    }
})

Once enabled, use the changeEmail function on the client to update a user’s email. The user must verify their current email before changing it.

await authClient.user.changeEmail({
    newEmail: "new-email@email.com",
    callbackURL: "/dashboard", //to redirect after verification
});

After verification, the new email is updated in the user table, and a confirmation is sent to the new address.

Change Password

Password of a user isn't stored in the user table. Instead, it's stored in the account table. To change the password of a user, you can use the changePassword function provided by the client. The changePassword function takes an object with the following properties:

await authClient.user.changePassword({
    newPassword: "newPassword123",
    currentPassword: "oldPassword123",
    revokeOtherSessions: true, // revoke all other sessions the user is signed into
});

Set Password

If a user was registered using oAuth or other providers, they won't have a password. In this case, you can use the setPassword function to set a password for the user. This will create a new credential account with the password.

await authClient.user.setPassword({
    password,
});

Accounts

Better Auth supports multiple authentication methods. Each authentication method is called a provider. For example, email and password authentication is a provider, Google authentication is a provider, etc.

When a user signs in using a provider, an account is created for the user. The account stores the authentication data returned by the provider. This data includes the access token, refresh token, and other information returned by the provider.

Account table

The account table stores the authentication data of the user. The account table has the following fields:

• id: The unique identifier of the account.
• userId: The id of the user.
• accountId: The id of the account. (optional)
• providerId: The id of the provider. (optional)
• accessToken: The access token of the account. Returned by the provider. (optional)
• refreshToken: The refresh token of the account. Returned by the provider. (optional)
• expiresAt: The time when the access token expires. (optional)
• password: The password of the account. Mainly used for email and password authentication. (optional)

Account linking

Account linking allows users to connect multiple authentication methods to a single account. Better Auth supports linking social sign-on or OAuth providers to an existing account if the provider returns a verified email.

You can also specify a list of trusted providers. If a user signs in using a trusted provider, the account is linked, even if the email verification status is not provided.

If account linking is disabled, accounts cannot be linked, regardless of the provider or email verification.

const auth = new BetterAuth({
    account: {
        accountLinking: {
            enabled: true,
            trustedProviders: ["google", "github"],
        }
    },
});

To link a credential-based account (email and password), users can either go through the "forgot password" flow or use the setPassword function if they are already logged in.

await authClient.user.setPassword({
    password,
});