Skip to main content

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.

API Reference / modelence / server / AuthConfig
AuthConfig = object
Defined in: packages/modelence/src/app/authConfig.ts:158 Authentication configuration for the application

Example

import { startApp } from 'modelence/server';

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

PropertyTypeDescriptionDefined in
allowDisposableEmails?booleanWhen 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 — 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:297
errorComponent?(props) => string | null | undefinedCustomizes 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:275
generateHandle?(props) => Promise<string> | stringCustom 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<string>. If the returned handle collides with an existing one, Modelence appends a numeric suffix automatically.packages/modelence/src/app/authConfig.ts:251
login?AuthOptionDeprecated Use AuthConfig.onAfterLogin and AuthConfig.onLoginError instead.packages/modelence/src/app/authConfig.ts:254
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:264
onAfterEmailVerification?(props) => voidFires 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:223
onAfterLogin?(props) => voidFires 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:182
onAfterOAuthLink?(props) => voidFires 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:236
onAfterSignup?(props) => voidFires 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:210
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:203
onEmailVerificationError?(props) => voidFires when email verification fails (invalid or expired token). Receives { provider, error, session, connectionInfo }.packages/modelence/src/app/authConfig.ts:229
onLoginError?(props) => voidFires 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:188
onOAuthLinkError?(props) => voidFires when OAuth account linking fails. Receives { provider, error, session, connectionInfo }.packages/modelence/src/app/authConfig.ts:242
onSignupError?(props) => voidFires 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:217
rateLimits?AuthRateLimitsConfigOverrides 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 for full semantics and examples.packages/modelence/src/app/authConfig.ts:284
signup?AuthOptionDeprecated Use AuthConfig.onAfterSignup and AuthConfig.onSignupError instead.packages/modelence/src/app/authConfig.ts:256
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:175
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:167