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
| Plugin | Server option | Client plugin | Status | Notes |
|---|---|---|---|---|
| Organization | organization | organizationClient() from better-auth/client/plugins | Supported | Needs 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-factor | twoFactor | twoFactorClient() from better-auth/client/plugins | Supported | Needs 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 OTP | emailOTP | emailOTPClient() from better-auth/client/plugins | Supported | Needs the email hook (a loopback SITE_URL logs codes instead). Codes are stored hashed. changeEmail and unknown keys are rejected. Adds no tables. |
| OAuth provider | oauth.mcp | oauthProviderClient() from @better-auth/oauth-provider/client | Supported for MCP | Only 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. |
| JWT | None | None | Built in | The library always installs it. It stores the keys that sign Convex session tokens and OAuth access tokens. You cannot configure it. |
| Anonymous | experimental.anonymous | anonymousClient() from better-auth/client/plugins | Experimental | Needs 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 number | Rejected | Rejected | Not supported | The 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.sendInvitationEmailtwoFactor.otpOptions.sendOTPemailOTP.sendVerificationOTP
Turn on a plugin
- Add the server option to
createBetterConvexAuth. - For anonymous, organization, two-factor, and the OAuth provider, add the plugin to
convex/betterAuth/schemaPlugins.tsand regenerate the auth schema. For the OAuth provider, see step 1 of Add MCP to your application. - 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.