Connect multiple authentication methods
A user signs in with email/password and later adds Google or another OAuth provider.
Better Auth · Pipe
account
An account is Better Auth’s record for an authentication method connected to a user. Account records support multiple providers, account listing, linking, unlinking, and account-specific provider operations.
How it works
The account configuration controls how Better Auth models and stores linked authentication methods. It can encrypt OAuth tokens and govern whether accounts may be linked, which providers are trusted for linking, and whether different email addresses are allowed.
Syntax
betterAuth({ account: { ... } })Parameters
| Name | Type | Description |
|---|---|---|
account | object | Account configuration object; documented options include modelName, fields, encryptOAuthTokens, storeStateStrategy, storeAccountCookie, and accountLinking. |
Returns
An account configuration that controls authentication-method records, OAuth-token storage, account cookies, and account-linking behavior.
Key points
- Every authentication method connected to a user gets its own account record.
- Use the Better Auth account record ID when an account-management API asks for
accountId. - The external provider identity is identified by combining the provider identifier with the provider-assigned account identifier.
listAccountsreturns all authentication methods associated with the signed-in user.- OAuth-backed accounts require provider credentials such as a client ID and client secret.
Example: Configure account options
import { betterAuth } from "better-auth";
export const auth = betterAuth({
account: {
encryptOAuthTokens: true,
accountLinking: {
enabled: true,
trustedProviders: ["google", "github", "email-password"],
allowDifferentEmails: false,
},
},
});Configures account storage behavior, OAuth-token encryption, and account-linking rules.
When to use it
List and unlink accounts
An application must show or remove the providers currently connected to a user.
Protect stored OAuth tokens
A provider returns OAuth tokens that should not be stored in plaintext.
Control account linking
A product needs strict rules about which providers may be linked.
Interview questions
QHow are Better Auth accounts identified?
An account represents one authentication method connected to a user. Its Better Auth record id is the account identifier used by account-management APIs, while the provider identity is represented by the providerId and provider-assigned accountId.
Follow-up: Why should an application retain the Better Auth record ID? Because unlinking and account-specific APIs require that record ID rather than the external provider subject identifier.
QWhat controls account linking?
Account linking is enabled by default. Users can associate additional social or OAuth methods when the provider confirms the email as verified; configuration can restrict trusted providers and whether different emails are accepted.
Follow-up: How would you prevent an untrusted provider from linking? Configure accountLinking.trustedProviders with only the permitted provider identifiers.
QHow should OAuth tokens and account data be stored?
encryptOAuthTokens: true encrypts OAuth tokens before they are stored in the database. For providers with large JWTs or production flows needing durable token storage, the documentation recommends database-backed storage.
Follow-up: What trade-off applies to cookie-based account storage? Large cookies may still hit browser or proxy cookie/header limits despite Better Auth chunking them.
Related
listAccountslinkAccountgetAccessTokenrefreshTokenaccountInfoaccountLinkingencryptOAuthTokensstoreAccountCookie