Basic Usage

Better Auth guide

Better Auth's basic usage guide applies to Convex as well. It covers signing in and out, social providers, plugins, and more. You will be using Better Auth directly in your project, so their guides are a primary reference.

Exceptions

There are a few areas in the Better Auth basic usage guide that work differently in Convex.

• Server side authentication

  Better Auth supports signing users in and out through server side functions. Because Convex functions run over websockets and don't return HTTP responses or set cookies, signing up/in/out must be done from the client via authClient.signIn.* methods.

• Schemas and migrations

  The basic usage guide includes information on database schema generation and migrations via the Better Auth CLI. This only applies for local installs, which support generating schemas. For projects not using local install, the default schema provided with the Better Auth component (preconfigured with the supported plugins) is used, and cannot be altered.

Using server methods with auth.api

Better Auth's server side auth.api methods can be used with your createAuth function and the component headers method. Here's an example implementing the changePassword server method.

export const updateUserPassword = mutation({
  args: {
    currentPassword: v.string(),
    newPassword: v.string(),
  },
  handler: async (ctx, args) => {
    // Many Better Auth server methods require a currently authenticated
    // user, so request headers have to be passed in so session cookies
    // can be parsed and validated. The `headers` utility can be used here.
    await createAuth(ctx).api.changePassword({
      body: {
        currentPassword: args.currentPassword,
        newPassword: args.newPassword,
      },
      headers: await authComponent.getHeaders(ctx),
    });
  },
});