The Better Auth Credentials Plugin provides a highly customizable mechanism for authenticating users against external systems like LDAP, custom APIs, or other credential-based services, integrating seamlessly with the Better Auth ecosystem. It is currently at version 0.5.2 and appears to have a relatively active release cadence, with several minor releases in recent months addressing bug fixes and compatibility. Key differentiators include full control over the authentication callback logic, optional auto sign-up, management of account linking and session creation, and flexible route customization with Zod schemas for validation and OpenAPI documentation. It's designed to complement, not replace, Better Auth's native email/password or username flows when integrating with third-party authentication sources. The plugin explicitly supports both server and client-side integration.
npm install better-auth-credentials-pluginVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates the server-side setup for the credentials plugin within a Better Auth instance, showing how to implement a custom authentication callback to verify user credentials against an external API. It also highlights the necessary client-side import pattern.
Ensure your `better-auth` peer dependency is updated to `^1.5.0` or newer, as specified in the plugin's `peerDependencies`.
Change client-side imports from `import { credentialsClient } from 'better-auth-credentials-plugin';` to `import { credentialsClient } from 'better-auth-credentials-plugin/client';`Ensure your `callback` function always returns an object containing a unique `email` property (e.g., `{ email: 'user@example.com', ...otherUserData }`).For standard password-based authentication, use Better Auth's built-in `emailAndPassword` or `username` plugins. Only use `better-auth-credentials-plugin` for integration with *external* credential systems like LDAP or custom APIs.
Consider setting a unique `providerId` in the plugin configuration (e.g., `credentials({ providerId: 'ldap', ... })`) and enabling `linkAccountIfExisting: true` if you want users to link multiple authentication methods to a single Better Auth account.Update your `better-auth` package to version `^1.5.0` or higher to match the plugin's requirements. Run `npm install better-auth@latest`.
Ensure your `callback` function returns an object with at least a valid `email` property. If using a custom `inputSchema`, verify the incoming `parsed` object from the client matches its requirements.
For client-side code, ensure you are importing from the `/client` subpath: `import { credentialsClient } from 'better-auth-credentials-plugin/client';`. Also, check that `better-auth-credentials-plugin` is correctly installed.Ensure your project is configured for ESM. Use `import { credentials } from 'better-auth-credentials-plugin';` instead of `const credentials = require('better-auth-credentials-plugin');`. If using a bundler, verify its configuration for resolving ESM packages.