> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelence.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AuthConfig
[API Reference](/api-reference/modelence/server/type-aliases/../../../index) / [modelence](/api-reference/modelence/server/type-aliases/../../index) / [server](/api-reference/modelence/server/type-aliases/../index) / AuthConfig
> **AuthConfig** = `object`
Defined in: [packages/modelence/src/app/authConfig.ts:164](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L164)
Authentication configuration for the application
## Example
```typescript theme={null}
import { startApp } from 'modelence/server';
import { time } from 'modelence';
startApp({
auth: {
validateSignup: ({ email, firstName, lastName, password, handle, avatarUrl }) => {
// Validating the signup data
if (!email || !password) {
throw new Error('Email and password are required');
}
},
onAfterLogin: ({ user }) => {
console.log('User logged in:', user.name);
// Redirect to dashboard
},
onLoginError: ({ error }) => {
console.error('Login failed:', error.message);
// Show error toast
},
onAfterSignup: ({ user }) => {
console.log('User signed up:', user.email);
// Send welcome email
},
onSignupError: ({ error }) => {
console.error('Signup failed:', error.message);
},
generateHandle: ({ email }) => {
console.log('Generating handle for:', email);
// Generate handle
return 'user123';
},
}
});
```
## Properties
| Property | Type | Description | Defined in |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowDisposableEmails?` | `boolean` | When `true`, the built-in disposable-email check is skipped during signup. Defaults to `false` (built-in check enforced). Set this to `true` when you want to enforce your own domain-policy logic via [onBeforeSignup](/api-reference/modelence/server/type-aliases/AuthConfig#onbeforesignup) — for example, a service that classifies domains as public/disposable/custom with its own data sources and cache. Skipping the built-in check without registering an `onBeforeSignup` hook means disposable emails will be allowed to sign up. | [packages/modelence/src/app/authConfig.ts:329](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L329) |
| `errorComponent?` | (`props`) => `string` \| `null` \| `undefined` | Customizes how OAuth authentication errors are rendered. By default, OAuth errors are returned as JSON; providing this returns a custom HTML response instead, which is useful when the OAuth flow runs in a browser context. Receives `{ error, statusCode }` and returns an HTML string (or `null`/`undefined` to fall back to the default JSON response). Always escape interpolated values to prevent XSS. | [packages/modelence/src/app/authConfig.ts:307](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L307) |
| `generateHandle?` | (`props`) => `Promise`\<`string`> \| `string` | Custom handle generator. If provided, overrides the default behavior (which derives the handle from the email local-part). Receives `{ email, firstName?, lastName? }` and returns the desired handle synchronously or as a `Promise`. If the returned handle collides with an existing one, Modelence appends a numeric suffix automatically. | [packages/modelence/src/app/authConfig.ts:257](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L257) |
| ~~`login?`~~ | [`AuthOption`](/api-reference/modelence/server/type-aliases/AuthOption) | **Deprecated** Use [AuthConfig.onAfterLogin](/api-reference/modelence/server/type-aliases/AuthConfig#onafterlogin) and [AuthConfig.onLoginError](/api-reference/modelence/server/type-aliases/AuthConfig#onloginerror) instead. | [packages/modelence/src/app/authConfig.ts:260](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L260) |
| `magicLink?` | `object` | Enables passwordless magic link authentication. Disabled by default. Requires an email provider and delivery settings under the `email` option (see `EmailConfig.magicLink`). **Example** `startApp({ auth: { magicLink: { enabled: true, allowSignup: true }, }, });` | [packages/modelence/src/app/authConfig.ts:279](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L279) |
| `magicLink.allowSignup?` | `boolean` | Allows a magic link (or its one-time code) to create an account when the email has no existing one — combined sign-in/sign-up, like OAuth. Disabled by default: unknown emails get the same generic "link sent" response but no email, and no account is ever auto-created. | [packages/modelence/src/app/authConfig.ts:287](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L287) |
| `magicLink.enabled?` | `boolean` | - | [packages/modelence/src/app/authConfig.ts:280](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L280) |
| `oauthAccountLinking?` | `"auto"` \| `"manual"` | Controls how OAuth providers handle existing accounts with matching email. - 'manual' (default): Returns an error when an OAuth login matches an existing email. - 'auto': Automatically links the OAuth provider to the existing account if the provider email is verified. | [packages/modelence/src/app/authConfig.ts:296](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L296) |
| `onAfterEmailVerification?` | (`props`) => `void` | Fires after a user's email is successfully verified (via the verification link or implicitly via password reset). Receives `{ provider, user, session, connectionInfo }`. | [packages/modelence/src/app/authConfig.ts:229](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L229) |
| `onAfterLogin?` | (`props`) => `void` | Fires after a successful login (email/password or OAuth) once the session has been linked to the user. Receives `{ provider, user, session, connectionInfo }`. Use for analytics, audit logging, or post-login side effects. | [packages/modelence/src/app/authConfig.ts:188](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L188) |
| `onAfterOAuthLink?` | (`props`) => `void` | Fires after an OAuth provider is linked to an existing account (either automatically when `oauthAccountLinking: 'auto'` or via an explicit link flow). Receives `{ provider, user, session, connectionInfo }`. | [packages/modelence/src/app/authConfig.ts:242](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L242) |
| `onAfterSignup?` | (`props`) => `void` | Fires after a successful signup once the user record is created and the session is linked. Receives `{ provider, user, session, connectionInfo }`. Common uses: send welcome email, create default workspace, track activation. | [packages/modelence/src/app/authConfig.ts:216](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L216) |
| `onBeforeSignup?` | (`props`) => `void` \| `Promise`\<`void`> | Hook fired after validation and the built-in disposable-email check, but before the new user document is inserted. Throwing aborts the signup — the thrown error is re-thrown to the caller and `onSignupError` fires. Use this to plug in a custom domain-policy check (e.g. a tenant-specific email-domain verification service) without having to disable the built-in disposable-email check. Invoked for `'email'` and `'magicLink'` provider signups. OAuth signups are not gated because OAuth providers (Google, GitHub, etc.) do not issue disposable accounts. | [packages/modelence/src/app/authConfig.ts:209](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L209) |
| `onEmailVerificationError?` | (`props`) => `void` | Fires when email verification fails (invalid or expired token). Receives `{ provider, error, session, connectionInfo }`. | [packages/modelence/src/app/authConfig.ts:235](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L235) |
| `onLoginError?` | (`props`) => `void` | Fires when a login attempt fails. Receives `{ provider, error, session, connectionInfo }`. Use for failure analytics or alerting — does NOT change the response sent to the client. | [packages/modelence/src/app/authConfig.ts:194](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L194) |
| `onOAuthLinkError?` | (`props`) => `void` | Fires when OAuth account linking fails. Receives `{ provider, error, session, connectionInfo }`. | [packages/modelence/src/app/authConfig.ts:248](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L248) |
| `onSignupError?` | (`props`) => `void` | Fires when a signup attempt fails (validation, duplicate email, etc.). Receives `{ provider, error, session, connectionInfo }`. Use for failure analytics — does NOT change the response sent to the client. | [packages/modelence/src/app/authConfig.ts:223](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L223) |
| `rateLimits?` | [`AuthRateLimitsConfig`](/api-reference/modelence/server/type-aliases/AuthRateLimitsConfig) | Overrides the built-in rate limits for authentication endpoints. Each rule you provide is merged into the defaults by `(bucket, type, window)`: matching tuples replace the default `limit`, new tuples are added, and unspecified defaults are preserved. See [AuthRateLimitsConfig](/api-reference/modelence/server/type-aliases/AuthRateLimitsConfig) for full semantics and examples. | [packages/modelence/src/app/authConfig.ts:316](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L316) |
| ~~`signup?`~~ | [`AuthOption`](/api-reference/modelence/server/type-aliases/AuthOption) | **Deprecated** Use [AuthConfig.onAfterSignup](/api-reference/modelence/server/type-aliases/AuthConfig#onaftersignup) and [AuthConfig.onSignupError](/api-reference/modelence/server/type-aliases/AuthConfig#onsignuperror) instead. | [packages/modelence/src/app/authConfig.ts:262](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L262) |
| `validateProfileUpdate?` | (`props`) => `void` \| `Promise`\<`void`> | Pre-update validation hook. Runs before a user's profile fields (`firstName`, `lastName`, `avatarUrl`, `handle`) are written. Throw to reject the update — the thrown message is surfaced to the client. May be async. | [packages/modelence/src/app/authConfig.ts:181](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L181) |
| `validateSignup?` | (`props`) => `void` \| `Promise`\<`void`> | Pre-signup validation hook. Runs before a new user is created during email/password signup, after format checks but before duplicate detection. Throw to reject the signup — the thrown message is surfaced to the client. Receives the raw signup payload (`email`, `password`, and optional `firstName`, `lastName`, `avatarUrl`, `handle`). May be async. | [packages/modelence/src/app/authConfig.ts:173](https://github.com/modelence/modelence/blob/0e072e44dd157ae8712ae82111cf4aa756460eba/packages/modelence/src/app/authConfig.ts#L173) |