This file is generated from the live auth app. Do not edit it by hand; regenerate it from apps/docs-site/ with bun run generate.
Generated from: apps/core/auth/package.json, apps/core/auth/src/platform/better-auth/auth.ts, apps/core/auth/src/index.ts
Better Auth packages detected
| Package | Version | Type | Why it matters here |
|---|
@better-auth/mcp | 1.7.0-rc.6 | Official addon | Auth dependency discovered in the auth app manifest. |
@better-auth/oauth-provider | 1.7.0-rc.6 | Official addon | Auth dependency discovered in the auth app manifest. |
@better-auth/passkey | 1.7.0-rc.6 | Official addon | Official Better Auth passkey addon enabling WebAuthn / passkey ceremonies. |
@better-auth/sso | 1.7.0-rc.6 | Official addon | Auth dependency discovered in the auth app manifest. |
@better-auth/stripe | 1.7.0-rc.6 | Official addon | Auth dependency discovered in the auth app manifest. |
@crown/better-auth-admin-access | workspace:* | Crown extension | Crown extension for platform-wide admin, GDPR, auditor, and support access flows. |
@crown/better-auth-external-structure | workspace:* | Crown extension | Crown extension for partner/external organization trees, invitations, and delegated access. |
@crown/better-auth-organization-archive | workspace:* | Crown extension | Crown extension for organization archive, soft-delete, restore, and cascade handling. |
@crown/better-auth-permissions | workspace:* | Crown extension | Crown extension for scoped roles, role templates, team grants, and permission checks. |
@crown/better-auth-workspace | workspace:* | Crown extension | Crown extension for workspaces, workspace teams, invitations, and active workspace context. |
better-auth | 1.7.0-rc.6 | Core | Core Better Auth runtime mounted by the auth service under /api/auth/**. |
Plugin stack in configured order
| # | Module | Source | Type | What it adds |
|---|
| 1 | Bearer Reads | ../../features/session/bearer-reads | Official addon | Bearer Reads is configured in the auth app. |
| 2 | Email OTP | better-auth/plugins | Official addon | Sends verification, reset-password, and security-code OTP emails through Better Auth. |
| 3 | Two Factor | better-auth/plugins | Official addon | Adds TOTP / OTP-based second-factor challenges, backup codes, and trusted-device cookies. |
| 4 | Two Factor Context | ../../features/two-factor/two-factor-context | Official addon | Two Factor Context is configured in the auth app. |
| 5 | Expired Session Cookies | ../../features/session/expired-session-cookies | Official addon | Expired Session Cookies is configured in the auth app. |
| 6 | Admin | better-auth/plugins | Official addon | Enables Better Auth admin capabilities for platform owner/admin roles. |
| 7 | Organization | better-auth/plugins | Official addon | Adds organizations, teams, invitations, and membership roles to Better Auth. |
| 8 | Workspace | @crown/better-auth-workspace | Crown extension | Adds Crown workspaces, workspace teams, invitations, and active workspace tracking. |
| 9 | Passkey | @better-auth/passkey | Official addon | Enables WebAuthn passkey registration and sign-in via @better-auth/passkey. |
| 10 | Organization Archive | @crown/better-auth-organization-archive | Crown extension | Adds archive, soft-delete, and restore lifecycle operations for organizations. |
| 11 | JWT | better-auth/plugins | Official addon | Signs short-lived JWTs, manages JWKS keys, and defines the outbound token payload. |
| 12 | External Structure | @crown/better-auth-external-structure | Crown extension | Adds hierarchical partner/external organization nodes, invitations, and delegated workspace access. |
| 13 | Permissions | @crown/better-auth-permissions | Crown extension | Adds scoped roles, role templates, effective-permission checks, and team-wide grants. |
| 14 | Admin Access | @crown/better-auth-admin-access | Crown extension | Adds platform-level admin access APIs for organizations, users, teams, workspaces, and GDPR actions. |
| 15 | Sso | @better-auth/sso | Official addon | Sso is configured in the auth app. |
| 16 | Sso Policy | ../../features/sso/sso-policy | Official addon | Sso Policy is configured in the auth app. |
| 17 | Billing Plugins | ../../features/billing/billing-plugins | Official addon | Billing Plugins is configured in the auth app. |
How Better Auth works in Crown
- Better Auth is mounted inside the Hono auth service at
/api/auth/**, so the browser talks to the service wrapper rather than to Better Auth directly. - The auth store uses
surrealAdapter(...), so Better Auth state lives in SurrealDB alongside the Crown auth schema. - Primary sign-in modes detected:
email + password, email OTP, passkey. - Email/password sign-in requires verified email before the normal session flow is considered complete.
- OTP-related flows default to a 10-minute validity window unless overridden by environment variables.
- A user creation hook bootstraps the first user as an owner, so initial platform setup happens inside the auth app rather than in separate seed logic.
- A session creation hook normalizes Surreal record IDs and auto-activates organization, workspace, and team context whenever the user membership graph is unambiguous.
- Trusted origins are configured explicitly, which keeps Better Auth, email links, passkeys, and cross-origin UI callbacks aligned with the deployed frontend origins.
- Cookie defaults are centralized, so session, two-factor, and trusted-device cookies share the same secure / httpOnly / sameSite policy envelope.
- The JWT plugin signs 15m tokens using EdDSA / Ed25519 and publishes JWKS for downstream verification.
- The auth service layers a token-exchange route on top of Better Auth so an existing token can be reissued for an alternate SurrealDB access scope.
- A passkey admin helper route lets privileged users inspect passkey records already persisted by Better Auth.
- Crown-specific role template, custom role, and assignment APIs are hosted beside Better Auth so permission authoring stays anchored to the same authenticated session context.
- Reference-numbering routes also live in the auth service, reusing the Better Auth session and resolved organization / workspace / team scope.
Session behavior detected
- Session inactivity expiry:
60 * 30 - Session refresh cadence:
60 - Fresh-session window:
60 * 5 - Cookie cache max age:
60
JWT claims detected
The Better Auth JWT payload currently includes: ac, activeOrganizationId, activeTeamId, activeWorkspaceId, db, email, emailVerified, false, id, ns, null, orgRole, role, sub, teamRole, twoFactorEnabled, twoFactorMethod, twoFactorMethods.
Auth-service endpoint groups detected
| Route / prefix | Methods | Why it exists | Matched paths |
|---|
/api/auth/** | GET, POST | Mounted Better Auth handler for sign-in, sign-up, sessions, password reset, passkeys, and plugin endpoints. | /api/auth/** |
/.well-known/jwks.json | GET | Stable JWKS alias used by downstream APIs and SurrealDB to verify Better Auth JWTs. | /.well-known/jwks.json |
/api/token/exchange-db | POST | Verifies an existing Better Auth JWT and mints a database-scoped replacement token. | /api/token/exchange-db |
/api/admin/user-passkeys | GET | Admin helper route for inspecting passkey credentials already stored for a user. | /api/admin/user-passkeys |
/api/reference-numbering/* | GET, POST | Crown auth-service extensions that use the authenticated org/workspace/team context for reference numbering. | /api/reference-numbering/context<br/>/api/reference-numbering/organization<br/>/api/reference-numbering/team<br/>/api/reference-numbering/workspace |
/api/role-templates* | DELETE, GET, PATCH, POST | Crown role-template APIs layered next to Better Auth authorization metadata. | /api/role-templates<br/>/api/role-templates/:id<br/>/api/role-templates/:id/roles |
/api/roles* | DELETE, GET, PATCH, POST | Custom role CRUD, template-diff, and migration APIs layered on top of the Better Auth session. | /api/roles<br/>/api/roles/:id<br/>/api/roles/:id/migrate<br/>/api/roles/:id/template-diff |
/api/role-assignments* | DELETE, GET, POST | Crown role-assignment APIs that attach custom roles to members in org/workspace/team scopes. | /api/role-assignments<br/>/api/role-assignments/:id |
/session | GET | Minimal authenticated echo of the Better Auth session and current user. | /session |
/api/bootstrap/status | GET | Checks whether the auth datastore already contains a privileged bootstrap user. | /api/bootstrap/status |
Generation note
- The auth flow diagram and this runtime summary are both derived from the auth app’s current Better Auth config and Hono routes.
- If the plugin list, JWT payload, or auth-service routes change, the next docs generation run updates these artifacts automatically.