AuthInstance
AuthInstance =
object
Defined in: packages/auth/src/types.ts:129
The initialized auth instance with methods for session management, role assignment, impersonation, and request handling.
Created by calling the initAuth() function returned from createAuth
with an AuthEnvConfig.
Properties
Section titled “Properties”api:
unknown
Defined in: packages/auth/src/types.ts:188
The underlying Better Auth instance, for escape-hatch usage.
createContext()
Section titled “createContext()”createContext: (
request) =>Promise<AuthContext>
Defined in: packages/auth/src/types.ts:134
Builds an AuthContext from the request’s session cookie.
Returns a context with user: null if the session is invalid or missing.
Parameters
Section titled “Parameters”request
Section titled “request”Request
Returns
Section titled “Returns”Promise<AuthContext>
getRoles()
Section titled “getRoles()”getRoles: (
userId) =>Promise<string[]>
Defined in: packages/auth/src/types.ts:144
Retrieves all roles assigned to a user.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
Returns
Section titled “Returns”Promise<string[]>
handler()
Section titled “handler()”handler: (
request) =>Promise<Response>
Defined in: packages/auth/src/types.ts:186
Forwards an HTTP request to the Better Auth handler for processing auth API routes.
Parameters
Section titled “Parameters”request
Section titled “request”Request
Returns
Section titled “Returns”Promise<Response>
impersonate()
Section titled “impersonate()”impersonate: (
adminUserId,targetUserId) =>Promise<void>
Defined in: packages/auth/src/types.ts:171
Starts an impersonation session where the admin acts as the target user.
Only users with roles listed in impersonation.allowedRoles can impersonate.
Parameters
Section titled “Parameters”adminUserId
Section titled “adminUserId”string
targetUserId
Section titled “targetUserId”string
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”If the admin user’s roles do not permit impersonation.
removeRole()
Section titled “removeRole()”removeRole: (
userId,role) =>Promise<void>
Defined in: packages/auth/src/types.ts:164
Removes a single role from a user.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
string
Returns
Section titled “Returns”Promise<void>
requireUser()
Section titled “requireUser()”requireUser: (
request) =>Promise<AuthenticatedContext>
Defined in: packages/auth/src/types.ts:142
Like createContext, but redirects to the login page
if the user is not authenticated. Sets a cfast_redirect_to cookie so the user
returns to the original URL after login.
Parameters
Section titled “Parameters”request
Section titled “request”Request
Returns
Section titled “Returns”Promise<AuthenticatedContext>
Throws
Section titled “Throws”A 302 redirect response when the user is not authenticated.
sendMagicLink()
Section titled “sendMagicLink()”sendMagicLink: (
params) =>Promise<void>
Defined in: packages/auth/src/types.ts:179
Sends a magic link email to the given address for passwordless authentication.
Parameters
Section titled “Parameters”params
Section titled “params”callbackURL?
Section titled “callbackURL?”string
Override the post-login redirect URL. Defaults to redirects.afterLogin.
string
The recipient’s email address.
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”If the magic link plugin is not configured.
setRole()
Section titled “setRole()”setRole: (
userId,role,caller?) =>Promise<void>
Defined in: packages/auth/src/types.ts:149
Assigns a single role to a user (additive, does not remove existing roles).
When caller.callerRoles is provided, validates against roleGrants rules.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
string
caller?
Section titled “caller?”callerRoles?
Section titled “callerRoles?”string[]
Returns
Section titled “Returns”Promise<void>
setRoles()
Section titled “setRoles()”setRoles: (
userId,roles,caller?) =>Promise<void>
Defined in: packages/auth/src/types.ts:158
Replaces all of a user’s roles with the given set.
When caller.callerRoles is provided, validates each role against roleGrants rules.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
string[]
caller?
Section titled “caller?”callerRoles?
Section titled “callerRoles?”string[]
Returns
Section titled “Returns”Promise<void>
stopImpersonating()
Section titled “stopImpersonating()”stopImpersonating: (
adminUserId) =>Promise<void>
Defined in: packages/auth/src/types.ts:173
Ends all active impersonation sessions for the given admin user.
Parameters
Section titled “Parameters”adminUserId
Section titled “adminUserId”string
Returns
Section titled “Returns”Promise<void>