Convex Plugin
Configuration options for the Convex Better Auth plugin
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.
import { convex } from "@convex-dev/better-auth/plugins";
import authConfig from "./auth.config";
export const createAuth = (ctx: GenericCtx<DataModel>) => {
return betterAuth({
// ...other options
plugins: [
convex({
authConfig,
}),
],
});
};Options
authConfig (required)
The Convex auth config from your project, typically exported from
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
Optional JWT configuration options.
| Property | Type | Default | Description |
|---|---|---|---|
expirationSeconds | number | 900 (15 minutes) | JWT token expiration in seconds |
definePayload | function | See below | Custom function to define JWT payload |
The default definePayload function includes all user fields except id and
image, plus the session ID and issued-at timestamp:
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,
}),
},
});The sessionId and iat (issued-at) fields are always added automatically to
the JWT payload.
jwks
Optional static JWKS string for performance optimization. When provided, the plugin uses the static JWKS instead of fetching from the database, eliminating network requests during token validation.
See Static JWKS for setup instructions.
convex({
authConfig,
jwks: process.env.JWKS,
});options
Optional Better Auth options, primarily used to pass the basePath when using 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 for the JWKS endpoint to be configured
correctly.
Client Plugin
The client plugin provides type inference for the Better Auth client. It has no configuration options.
import { createAuthClient } from "better-auth/react";
import { convexClient } from "@convex-dev/better-auth/plugins";
export const authClient = createAuthClient({
plugins: [convexClient()],
});