Persist an OAuth/OIDC account
An OAuth or OIDC sign-in creates a provider account for a user.
Auth.js · Enum
linkAccount
linkAccount is an optional Auth.js adapter method that persists an account connection in the database. Auth.js uses it internally, and applications may use it for manual linking.
How it works
The optional adapter method receives an account object and creates its database record. Auth.js invokes it internally when an account is linked, while an adapter may also expose it for manual linking; the method can resolve to no value, null, or the stored account.
Syntax
optional linkAccount(account): Promise<void> | Awaitable<undefined | null | AdapterAccount>Parameters
| Name | Type | Description |
|---|---|---|
account | AdapterAccount | The account connection to persist for the user and provider. |
Returns
Promise<void> | Awaitable<undefined | null | AdapterAccount>
Key points
linkAccountis an optional method on the adapter interface and accepts one account argument.- The method may also resolve to
undefined,null, or anAdapterAccount. - Its primary persistence responsibility is creating the linked Account record.
- OAuth or OIDC provider sign-ins produce OAuth/OIDC account records.
- Email-provider sign-ins produce Email account records.
- The data model permits several provider accounts to belong to one user.
Common mistakes
- Although Auth.js calls this method as part of its internal flow, manual linking is also possible only when the adapter supports it.
- The supplied account represents a provider connection, not a standalone user record.
Example: Implement linkAccount
import type { Adapter, AdapterAccount } from "next-auth/adapters";
export const adapter: Adapter = {
async linkAccount(account: AdapterAccount) {
await db.account.create({ data: account });
return account;
},
};Implement the adapter method to persist the account record, then return the created account.
When to use it
Persist an Email account
An Email provider sign-in creates an associated account record.
Support manual account linking
A signed-in user intentionally connects another provider.
Interview questions
QWhat does linkAccount do and what can it return?
linkAccount is an optional adapter method that receives an account and creates the corresponding Account record in the database. Its return type may resolve to void, undefined, null, or an AdapterAccount.
Follow-up: Why is the method optional? The core flow can use an adapter implementation when account persistence is configured, while adapters that do not support this operation need not expose it.
QWhen is linkAccount called?
Auth.js invokes the method internally when it needs to persist a linked account. The same method can optionally support an application's manual account-linking flow.
Follow-up: What must manual linking additionally protect against? The application should authorize the signed-in user and validate the account association before writing it.
QHow does an Auth.js account relate to a user?
An account connects a user to a provider, and one user may have multiple accounts. OAuth/OIDC accounts arise from OAuth sign-ins, while Email accounts arise from Email-provider sign-ins.
Follow-up: How would you model the relationship? Store multiple account rows for one user, with each row identifying its provider connection.
Related
AdapterAdapterAccountunlinkAccountcreateUsergetUserByAccount