Skip to main content

Better Auth plugin support

See which Better Auth plugins work with createBetterConvexAuth and what each one needs.

createBetterConvexAuth installs the Better Auth plugins itself. It does not accept a plugins option. You turn on a supported plugin with its own option. The browser client accepts only the matching client plugins in defineConvexAuthClient. Any other client plugin fails at startup.

Supported plugins

PluginServer optionClient pluginStatusNotes
OrganizationorganizationorganizationClient() from better-auth/client/pluginsSupportedNeeds a local auth component. Teams work with teams: { enabled: true }. Invitation email goes through the email hook. Accepting an invitation needs a verified email by default.
Two-factortwoFactortwoFactorClient() from better-auth/client/pluginsSupportedNeeds a local auth component. One-time codes go through the email hook. Turning it on ends the person's other sessions. Rejected together with emailOTP, socialProviders, or oidc, because those sign-ins skip the second factor.
Email OTPemailOTPemailOTPClient() from better-auth/client/pluginsSupportedNeeds the email hook (a loopback SITE_URL logs codes instead). Codes are stored hashed. changeEmail and unknown keys are rejected. Adds no tables.
OAuth provideroauth.mcpoauthProviderClient() from @better-auth/oauth-provider/clientSupported for MCPOnly the MCP profile. A local auth component also needs it in the schema plugins. Dynamic client registration, UserInfo, and OpenID Connect discovery are off. See Delegated OAuth and MCP.
JWTNoneNoneBuilt inThe library always installs it. It stores the keys that sign Convex session tokens and OAuth access tokens. You cannot configure it.
Anonymousexperimental.anonymousanonymousClient() from better-auth/client/pluginsExperimentalNeeds a local auth component. Cannot be combined with twoFactor. See Guest users.
Any other plugin, for example admin, API key, passkey, magic link, username, OAuth popup, or phone numberRejectedRejectedNot supportedThe factory rejects plugins, and the client rejects unknown plugin IDs.

Email and password sign-in, email verification, social providers, and company sign-in are core options, not plugins. Configure them with emailAndPassword, emailVerification, socialProviders, and oidc. See Social sign-in, Company sign-in, and Transactional auth email. The Better Auth genericOAuth plugin stays rejected; use oidc for an OpenID Connect identity provider.

Options the library sets for you

Each supported plugin accepts the normal Better Auth options, except the email callbacks. The email hook sends every auth email, so these options fail with AUTH_CONFIG_INVALID:

  • organization.sendInvitationEmail
  • twoFactor.otpOptions.sendOTP
  • emailOTP.sendVerificationOTP

Turn on a plugin

  1. Add the server option to createBetterConvexAuth.
  2. For anonymous, organization, two-factor, and the OAuth provider, add the plugin to convex/betterAuth/schemaPlugins.ts and regenerate the auth schema. For the OAuth provider, see step 1 of Add MCP to your application.
  3. Add the client plugin to defineConvexAuthClient.

Better Auth plugins shows each step with the organization plugin.

Why other plugins are rejected

Each plugin adds routes, tables, and cookies. The library checks those parts against its session and token rules before it supports a plugin. A plugin that is not in the table has no such check, so the factory rejects it instead of running it without one. To ask for a plugin, open an issue in the repository.