Identity Schema

The identity option on createAuth defines the schema Aura Auth uses to validate and shape user identity data. The schema you provide is also used to derive the User and Session types used across the rest of the library, so setting it up correctly gets you type-safe access to your custom fields everywhere User/Session are used.

import { createAuth } from "@aura-stack/auth"
import { identitySchema, zod } from "@aura-stack/auth/identity/zod"

export const auth = createAuth({
  identity: {
    schema: identitySchema,
    unknownKeys: "strip",
    skipValidation: false,
  },
})

schemaCopy Anchor Link

Zod, Valibot, ArkType, and TypeBox are supported as the first-class and import its default schema from @aura-stack/auth/identity/:schema.

Built-in type inference (via InferUser/InferSession) is supported for Zod, Valibot, and ArkType. TypeBox is supported for validation but does not support direct type inference — see the Type Inference section for the workaround.

Each supported validator ships a default identitySchema containing the required base fields. Extend it with whatever additional fields your application needs.

import { createAuth } from "@aura-stack/auth"
import { identitySchema, zod } from "@aura-stack/auth/identity/zod"

const schema = identitySchema.extend({
  role: zod.enum(["admin", "user"]),
})

export const auth = createAuth({
  identity: {
    schema,
  },
})

unknownKeysCopy Anchor Link

By default, fields present on an incoming identity object but absent from your schema are silently removed (strip). Change this with unknownKeys if you need unvalidated passthrough fields, or want unexpected fields to fail loudly during development.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  identity: {
    unknownKeys: "strict", // throws if the identity object has fields outside the schema
  },
})

skipValidationCopy Anchor Link

When schema validation isn't relevant to your application, set skipValidation to true to accept any shape of identity object without enforcement.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  identity: {
    skipValidation: true,
  },
})

Type inferenceCopy Anchor Link

Aura Auth provides utility types to infer User and Session from your identity schema, so the rest of your application gets type safety and autocompletion on custom fields without manual duplication.

Infer directly from the auth instance with InferUser/InferSession, or from the schema itself with UserFrom/SessionFrom.

import { createAuth } from "@aura-stack/auth"
import { identitySchema } from "@aura-stack/auth/identity/zod"
import type { UserFrom, SessionFrom, InferUser, InferSession } from "@aura-stack/auth/identity"

type _User = UserFrom<typeof identitySchema>
type _Session = SessionFrom<typeof identitySchema>

export const auth = createAuth({
  oauth: [],
  identity: {
    schema: identitySchema,
  },
})

export type User = InferUser<typeof auth>
export type Session = InferSession<typeof auth>