Convex Plugin

Configuration reference for the Convex Better Auth server and client plugins

The Convex plugin integrates Better Auth with Convex by managing JWT generation, cookie handling, and JWKS endpoints for token validation.

Server plugin

The server plugin is required for Convex + Better Auth integration. Add it to your Better Auth plugins array.

convex/auth.ts

import { betterAuth } from "better-auth/minimal";
import { convex } from "@convex-dev/better-auth/plugins";
import authConfig from "./auth.config";
import { type GenericCtx } from "@convex-dev/better-auth";
import { type DataModel } from "./_generated/dataModel";
import { authComponent } from "./auth";

export const createAuth = (ctx: GenericCtx<DataModel>) => {
  return betterAuth({
    database: authComponent.adapter(ctx),
    plugins: [
      convex({
        authConfig,
      }),
    ],
  });
};

Options

authConfig · AuthConfig · required

The Convex auth config for your project. Typically exported from convex/auth.config.ts.

The config must include a provider with applicationID: "convex". Use getAuthConfigProvider() from @convex-dev/better-auth/auth-config to generate it:

convex/auth.config.ts

import { type AuthConfig } from "convex/server";
import { getAuthConfigProvider } from "@convex-dev/better-auth/auth-config";

export default {
  providers: [getAuthConfigProvider()],
} satisfies AuthConfig;

jwt · object

Optional JWT configuration.

Show jwt options

jwt.expirationSeconds · number · default: "900"

JWT token lifetime in seconds. Defaults to 15 minutes (900 seconds).

jwt.definePayload · function

Custom function to define the JWT payload. Receives { user, session } and returns a plain object.

The sessionId and iat (issued-at) fields are always appended automatically regardless of what this function returns.

Default behavior — includes all user fields except id and image, plus sessionId and iat:

definePayload: ({ user, session }) => ({
  ...omit(user, ["id", "image"]),
  sessionId: session.id,
  iat: Math.floor(new Date().getTime() / 1000),
});

Example: custom payload

convex({
  authConfig,
  jwt: {
    expirationSeconds: 60 * 30, // 30 minutes
    definePayload: ({ user, session }) => ({
      name: user.name,
      email: user.email,
      role: user.role,
      sessionId: session.id,
    }),
  },
});

jwks · string

Optional static JWKS string for performance optimization. When provided, the plugin uses this value instead of fetching JWKS from the database, eliminating network round-trips during token validation.

See Static JWKS for setup instructions.

convex({
  authConfig,
  jwks: process.env.JWKS,
});

options · BetterAuthOptions

Optional Better Auth options passed to the plugin. Currently used primarily to provide a custom basePath when your Better Auth config uses a non-default path.

convex({
  authConfig,
  options: {
    basePath: "/custom/auth/path",
  },
});

If your Better Auth configuration uses a custom basePath, you must pass the same value in options.basePath so the JWKS endpoint URL is constructed correctly. A mismatch will cause token validation to fail.

---

Client plugin

The client plugin provides type inference for the Better Auth client so response types from Convex-specific endpoints are available. It has no configuration options.

lib/auth-client.ts

import { createAuthClient } from "better-auth/react";
import { convexClient } from "@convex-dev/better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [convexClient()],
});