---
title: Auth Config
description: Auth Config protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Better-Auth Configuration Protocol

Defines the configuration required to initialize the Better-Auth kernel.

Used in server-side configuration injection.

<Callout type="info">
**Source:** `packages/spec/src/system/auth-config.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { AdvancedAuthConfig, AuthConfig, AuthPluginConfig, AuthProviderConfig, EmailAndPasswordConfig, EmailVerificationConfig, MutualTLSConfig, OidcProviderConfig, OidcProvidersConfig, SocialProviderConfig } from '@objectstack/spec/system';
import type { AdvancedAuthConfig, AuthConfig, AuthPluginConfig, AuthProviderConfig, EmailAndPasswordConfig, EmailVerificationConfig, MutualTLSConfig, OidcProviderConfig, OidcProvidersConfig, SocialProviderConfig } from '@objectstack/spec/system';

// Validate data
const result = AdvancedAuthConfig.parse(data);
```

---

## AdvancedAuthConfig

Advanced / low-level Better-Auth options

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **crossSubDomainCookies** | `Object` | optional | Share auth cookies across subdomains (critical for *.example.com multi-tenant) |
| **useSecureCookies** | `boolean` | optional | Force Secure flag on cookies |
| **disableCSRFCheck** | `boolean` | optional | ⚠ Disable CSRF check — security risk, use with caution |
| **cookiePrefix** | `string` | optional | Prefix for auth cookie names |


---

## AuthConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **secret** | `string` | optional | Encryption secret |
| **baseUrl** | `string` | optional | Base URL for auth routes |
| **uiBasePath** | `string` | ✅ | Basename where the auth UI (Console) is mounted (default `/_console`) |
| **databaseUrl** | `string` | optional | Database connection string |
| **providers** | `Object[]` | optional |  |
| **plugins** | `Object` | optional |  |
| **session** | `Object` | optional |  |
| **trustedOrigins** | `string[]` | optional | Trusted origins for CSRF protection. Supports wildcards (e.g. "https://*.example.com"). The baseUrl origin is always trusted implicitly. |
| **socialProviders** | `Record<string, Record<string, any>>` | optional | Social/OAuth provider map forwarded to better-auth socialProviders. Keys are provider ids (google, github, apple, …). |
| **oidcProviders** | `Object[]` | optional | List of OIDC/OAuth2 providers for enterprise SSO. Product or enterprise packages can pass this directly or contribute it through auth:configure. |
| **emailAndPassword** | `Object` | optional | Email and password authentication options forwarded to better-auth |
| **emailVerification** | `Object` | optional | Email verification options forwarded to better-auth |
| **advanced** | `Object` | optional | Advanced / low-level Better-Auth options |
| **mutualTls** | `Object` | optional | Mutual TLS (mTLS) configuration |


---

## AuthPluginConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **organization** | `boolean` | ✅ | Enable Organization/Teams support (frontend AuthProvider expects this enabled) |
| **twoFactor** | `boolean` | ✅ | Enable 2FA |
| **passkeys** | `boolean` | ✅ | Enable Passkey support |
| **magicLink** | `boolean` | ✅ | Enable Magic Link login |
| **oidcProvider** | `boolean` | ✅ | Enable the OpenID Connect provider plugin (acts as an OIDC IdP) |
| **deviceAuthorization** | `boolean` | ✅ | Enable RFC 8628 Device Authorization Grant (CLI / TV-style login) |
| **admin** | `boolean` | ✅ | Enable platform admin operations (ban/unban, set-password, impersonate, set-role) |


---

## AuthProviderConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Provider ID (github, google) |
| **clientId** | `string` | ✅ | OAuth Client ID |
| **clientSecret** | `string` | ✅ | OAuth Client Secret |
| **scope** | `string[]` | optional | Requested permissions |


---

## EmailAndPasswordConfig

Email and password authentication options forwarded to better-auth

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable email/password auth |
| **disableSignUp** | `boolean` | optional | Disable new user registration via email/password |
| **requireEmailVerification** | `boolean` | optional | Require email verification before creating a session |
| **minPasswordLength** | `number` | optional | Minimum password length (default 8) |
| **maxPasswordLength** | `number` | optional | Maximum password length (default 128) |
| **resetPasswordTokenExpiresIn** | `number` | optional | Reset-password token TTL in seconds (default 3600) |
| **autoSignIn** | `boolean` | optional | Auto sign-in after sign-up (default true) |
| **revokeSessionsOnPasswordReset** | `boolean` | optional | Revoke all other sessions on password reset |


---

## EmailVerificationConfig

Email verification options forwarded to better-auth

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **sendOnSignUp** | `boolean` | optional | Automatically send verification email after sign-up |
| **sendOnSignIn** | `boolean` | optional | Send verification email on sign-in when not yet verified |
| **autoSignInAfterVerification** | `boolean` | optional | Auto sign-in the user after email verification |
| **expiresIn** | `number` | optional | Verification token TTL in seconds (default 3600) |


---

## MutualTLSConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable mutual TLS authentication |
| **clientCertRequired** | `boolean` | ✅ | Require client certificates for all connections |
| **trustedCAs** | `string[]` | ✅ | PEM-encoded CA certificates or file paths |
| **crlUrl** | `string` | optional | Certificate Revocation List (CRL) URL |
| **ocspUrl** | `string` | optional | Online Certificate Status Protocol (OCSP) URL |
| **certificateValidation** | `Enum<'strict' \| 'relaxed' \| 'none'>` | ✅ | Certificate validation strictness level |
| **allowedCNs** | `string[]` | optional | Allowed Common Names (CN) on client certificates |
| **allowedOUs** | `string[]` | optional | Allowed Organizational Units (OU) on client certificates |
| **pinning** | `Object` | optional | Certificate pinning configuration |


---

## OidcProviderConfig

OIDC / Generic OAuth2 provider configuration for enterprise SSO

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **providerId** | `string` | ✅ | Unique identifier for this provider (e.g., okta, azure-ad) |
| **name** | `string` | optional | Display name shown in the UI (defaults to providerId) |
| **discoveryUrl** | `string` | optional | OIDC discovery URL (.well-known/openid-configuration). When provided, authorizationUrl/tokenUrl/userInfoUrl are fetched automatically. |
| **issuer** | `string` | optional | Expected issuer identifier for token validation |
| **authorizationUrl** | `string` | optional | OAuth2 authorization endpoint (optional if discoveryUrl is set) |
| **tokenUrl** | `string` | optional | OAuth2 token endpoint (optional if discoveryUrl is set) |
| **userInfoUrl** | `string` | optional | OAuth2 userinfo endpoint (optional if discoveryUrl is set) |
| **clientId** | `string` | ✅ | OAuth2 client ID |
| **clientSecret** | `string` | ✅ | OAuth2 client secret |
| **scopes** | `string[]` | optional | Requested scopes (default: openid email profile) |
| **pkce** | `boolean` | optional | Enable PKCE (recommended for public clients) |


---


---


---

