AuthConfig

AuthConfig<P> = object

Defined in: packages/auth/src/types.ts:90

Configuration for createAuth.

Defines authentication methods, session behavior, role management rules, and integration with @cfast/permissions.

The generic parameter P captures the concrete Permissions object passed to createAuth, which lets TypeScript narrow anonymousRoles and defaultRoles to the exact role union declared in the permissions config (e.g. "admin" | "editor" | "reader"). Passing an unknown role is then a compile-time error instead of a silent runtime surprise. Callers that supply a loosely-typed Permissions<readonly string[]> fall back to the historical string[] shape, so this is a non-breaking refinement.

Type Parameters

P

P extends Permissions<readonly string[]> = Permissions<readonly string[]>

Properties

anonymousRoles?

optional anonymousRoles: RoleNameOf<P>[]

Defined in: packages/auth/src/types.ts:150

Roles assigned to unauthenticated (anonymous) requests for permission resolution.

Constrained to the role union from AuthConfig.permissions — passing a role that was not declared in definePermissions() is a TS error.

---

defaultRoles?

optional defaultRoles: RoleNameOf<P>[]

Defined in: packages/auth/src/types.ts:158

Default roles assigned to authenticated users who have no explicit role assignments. Defaults to ["reader"].

Constrained to the role union from AuthConfig.permissions — passing a role that was not declared in definePermissions() is a TS error.

---

impersonation?

optional impersonation: object

Defined in: packages/auth/src/types.ts:164

Impersonation feature configuration.

allowedRoles?

optional allowedRoles: string[]

Roles permitted to impersonate other users. Defaults to ["admin"].

---

magicLink?

optional magicLink: object

Defined in: packages/auth/src/types.ts:128

Magic link email configuration. Required to enable magic link authentication.

sendMagicLink()

sendMagicLink: (params) => Promise<void>

Callback to send the magic link email. Receives the user’s email and the login URL.

Parameters

params

email

string

url

string

Returns

Promise<void>

---

passkeys?

optional passkeys: object

Defined in: packages/auth/src/types.ts:98

WebAuthn passkey configuration. Required to enable passkey authentication.

rpId

rpId: string | (request) => string

Relying party identifier, typically the app’s domain (e.g., "myapp.com").

Accepts either a static string or a function that resolves the RP ID from the incoming request. Use the function form for multi-tenant deployments that serve multiple domains from a single worker — the request-aware variant lets you return the actual hostname the user is connecting from instead of hard-coding a single value at factory time. The function form requires calling initAuth(env, request) so the request is available when Better Auth is constructed.

Examples

passkeys: { rpName: "My App", rpId: "myapp.com" }

passkeys: {
  rpName: "My App",
  rpId: (request) => new URL(request.url).hostname,
}

rpName

rpName: string

Relying party display name shown during WebAuthn registration.

---

permissions

permissions: P

Defined in: packages/auth/src/types.ts:94

The permissions config from definePermissions(). Roles are inferred from this.

---

redirects?

optional redirects: object

Defined in: packages/auth/src/types.ts:138

Redirect paths for the authentication flow.

afterLogin?

optional afterLogin: string

Where to redirect after successful login. Defaults to "/".

loginPath?

optional loginPath: string

Where to send unauthenticated users. Defaults to "/login".

---

roleGrants?

optional roleGrants: Record<string, string[]>

Defined in: packages/auth/src/types.ts:162

Maps each role to the set of roles it is allowed to assign. Controls who can promote whom.

---

roleTableName?

optional roleTableName: string

Defined in: packages/auth/src/types.ts:160

Custom table name for storing role assignments. Defaults to "roles".

---

schema?

optional schema: Record<string, unknown>

Defined in: packages/auth/src/types.ts:96

Optional Drizzle schema override for the Better Auth database adapter.

---

session?

optional session: object

Defined in: packages/auth/src/types.ts:133

Session lifetime configuration.

expiresIn?

optional expiresIn: string

How long sessions last before expiring (e.g., "30d", "12h", "60m"). Defaults to "30d".

---

templates?

optional templates: object

Defined in: packages/auth/src/types.ts:169

Custom email template functions.

magicLink()?

optional magicLink: (props) => string

Returns an HTML string for the magic link email. Receives the login URL and recipient email.

Parameters

props

email

string

url

string

Returns

string