Auth

The auth block defines your app's authentication model: sign-in providers, session lifetime, account linking, password policy, and principal attributes.

This is app-user authentication only — not delegated provider access (integrations {}), machine-to-machine route auth (apiKeys {}), or platform login (kizaki login).

Syntax

auth {
  providers: [email, google, github],
  sessionDuration: 30d,
  linking: manual,

  password {
    minLength: 12,
    requireUppercase: true,
    requireDigit: true,
    requireSpecial: true,
    blockCommon: true,
    breachCheck: true,
  }

  principal {
    displayName: string @from(Profile.displayName),
    organizationId: Organization.id @selectFrom(OrgMembership.orgId),
    organizationRole: OrgRole @from(
      OrgMembership.role,
      where OrgMembership.orgId == principal.organizationId
    ),
  }
}

What auth {} Controls

• Sign-in methods available in your app
• Session lifetime for authenticated users
• Account-linking policy when multiple providers exist
• Password policy for email/password accounts
• Shape of principal.* used across policies and server code

What It Does Not Control

• Provider API access on the user's behalf — use integrations {}.
• Machine credentials for routes — use apiKeys {} plus routes(..., auth: apiKey(scope)).
• Whether a route requires a signed-in user — use routes(..., auth: session).

Field Reference

providers

auth {
  providers: [email, google, github],
}

Supported values: email, google, github. Apple is not currently supported.

• email enables password-based signup, login, verification, reset, and password linking.
• google and github enable OAuth-based sign-in.
• Providers not declared here fail closed at runtime. Kizaki does not expose a working auth flow for undeclared providers.

sessionDuration

auth {
  providers: [email],
  sessionDuration: 30d,
}

Duration literal: 7d, 30d, 12h, etc.

sessionDuration controls the lifetime stamped onto issued auth sessions and the session cookie derived from them.

linking

Controls whether users can attach multiple sign-in methods to one account.

auth {
  providers: [email, google, github],
  linking: manual,
}

Defaults: manual when more than one provider is configured, disabled otherwise. Setting linking: manual with one provider emits warning E1112.

password

auth {
  providers: [email],

  password {
    minLength: 12,
    requireUppercase: true,
    requireLowercase: true,
    requireDigit: true,
    requireSpecial: true,
    minCharacterTypes: 3,
    blockCommon: true,
    breachCheck: true,
  }
}

Only applies when email is a configured provider. A good baseline: minLength: 12, blockCommon: true, breachCheck: true.

principal

The principal block defines which identity-related values are available as principal.* in policies and server code. It shapes policy conditions, server-function identity context, multi-tenant scoping, and user-facing UI identity data.

Two source patterns:

@from(...)

Single derived value. Use for profile fields and stable user attributes.

principal {
  displayName: string @from(Profile.displayName),
}

@selectFrom(...)

User-selected context value. Use for multi-tenant apps where a user belongs to multiple organizations.

principal {
  organizationId: Organization.id @selectFrom(OrgMembership.orgId),
}

Combining Them

auth {
  providers: [email, google],
  sessionDuration: 30d,

  principal {
    organizationId: Organization.id @selectFrom(OrgMembership.orgId),
    organizationRole: OrgRole @from(
      OrgMembership.role,
      where OrgMembership.orgId == principal.organizationId
    ),
  }
}

This gives the principal both a selected tenant and a role inside that tenant.

Recommended Patterns

auth {
  providers: [email, google],
  sessionDuration: 30d,

  password {
    minLength: 12,
    blockCommon: true,
    breachCheck: true,
  }

  principal {
    displayName: string @from(Profile.displayName),
    organizationId: Organization.id @selectFrom(OrgMembership.orgId),
  }
}

• Start with the providers you need.
• Keep principal small and stable.
• Store business-specific user data in your own entities, not in principal.
• Use @from for stable single-valued identity data.
• Use @selectFrom for current-tenant or current-workspace context.

Runtime Behavior

The compiler parses auth {} and emits config into the artifact. The auth service exposes /__auth/* endpoints around that config, and the runtime treats the compiled provider list, linking mode, and session duration as authoritative.

Production OAuth has two callback paths:

• Hosted/default domains use the shared Kizaki auth callback/client.
• Custom domains can use a direct callback on the app's own domain with app-scoped provider credentials from kizaki/apps/<app_id>/envs/production/auth/oidc.

Browser code can read the public auth surface at runtime through getAuthConfig() from @kizaki/sdk/auth.

Related Docs

• Authentication Guide
• Add Authentication
• Routes
• API Keys
• Integrations
• TypeScript Auth API