> ## 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:160](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L160)
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:299](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L299) |
| `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:277](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L277) |
| `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:253](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L253) |
| ~~`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:256](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L256) |
| `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:266](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L266) |
| `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:225](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L225) |
| `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:184](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L184) |
| `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:238](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L238) |
| `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:212](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L212) |
| `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. Currently only invoked for `'email'` provider signups. OAuth signups are not gated because OAuth providers (Google, GitHub, etc.) do not issue disposable accounts. | [packages/modelence/src/app/authConfig.ts:205](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L205) |
| `onEmailVerificationError?` | (`props`) => `void` | Fires when email verification fails (invalid or expired token). Receives `{ provider, error, session, connectionInfo }`. | [packages/modelence/src/app/authConfig.ts:231](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L231) |
| `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:190](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L190) |
| `onOAuthLinkError?` | (`props`) => `void` | Fires when OAuth account linking fails. Receives `{ provider, error, session, connectionInfo }`. | [packages/modelence/src/app/authConfig.ts:244](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L244) |
| `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:219](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L219) |
| `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:286](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L286) |
| ~~`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:258](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L258) |
| `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:177](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L177) |
| `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:169](https://github.com/modelence/modelence/blob/f614ecc6811cdda9670d612872c8ff49a49c5e28/packages/modelence/src/app/authConfig.ts#L169) |