Identity and auth models

These models live in the Postgres auth schema and are declared only in packages/database/prisma/schema.prisma. better-auth reads and writes them through prismaAdapter(db, { provider: 'postgresql' }) in packages/auth/src/auth.ts. Table names are lowercase singular (user, session, member) because better-auth expects them that way. advanced.database.generateId is false, so ids come from the Prisma @default(cuid()), not from better-auth.

createdAt and updatedAt on most auth tables have no database default. better-auth supplies the values. If you insert rows by hand, set them yourself.

How auth rows link to domain rows

There is no foreign key between the auth and public schemas. The links are plain string columns:

Auth row	Domain row	Link
`Organization.id`	`Studio`	`Studio.externalOrgId` (unique)
`User.id` of a staff member	`Coach`	`Coach.externalUserId`, unique per studio with `@@unique([studioId, externalUserId])`
`User.id` of a trainee	`Client`	`Client.externalUserId`, unique per studio
`Member.role`	`Coach.role` and the request role	Mapped in the web lane middleware (`apps/core-api/src/middleware/web-context.ts`)

A staff user can belong to several organizations, so one User can map to several Coach rows, one per studio. The web lane upserts the owner’s Coach row on first request with role: 'HEAD_COACH'.

`User`

Table auth.user. One row per person who can sign in: studio owners, staff and trainees.

Field	Type	Meaning
`id`	`String`	cuid primary key.
`name`	`String`	Display name.
`email`	`String`	Unique.
`emailVerified`	`Boolean`	Set by better-auth after verification.
`image`	`String?`	Avatar URL.
`username`	`String?`	Unique. From the `username()` plugin.
`displayUsername`	`String?`	Username as typed, before normalization.
`role`	`String?`	Platform role from the `admin()` plugin. `admin` marks a Perform super admin. This is not the studio role.
`banned`, `banReason`, `banExpires`	`Boolean?`, `String?`, `DateTime?`	Admin plugin ban state.
`onboardingComplete`	`Boolean`	Default `false`. An additional field declared in `user.additionalFields`. The browser can set it, so server logic does not trust it for plan decisions.
`paymentsCustomerId`	`String?`	Payment provider customer id when billing is attached to a user. Perform attaches billing to the organization, so this is normally empty.
`locale`	`String?`	Preferred UI locale. Additional field.
`twoFactorEnabled`	`Boolean?`	From the two-factor plugin.
`lastActiveOrganizationId`	`String?`	Last organization the user worked in. Additional field.
`phoneNumber`	`String?`	Unique. From the `phoneNumber()` plugin. Used for WhatsApp OTP login.
`phoneNumberVerified`	`Boolean?`	Set after a successful phone OTP.
`createdAt`, `updatedAt`	`DateTime`	Supplied by better-auth.

Unique constraints: email, username, phoneNumber. Relations: sessions, accounts, passkeys, invitations (as inviter), purchases, members, twofactors, notifications, notificationPreferences. All cascade on user delete.

`Session`

Table auth.session. One row per signed-in device.

Field	Type	Meaning
`id`	`String`	cuid.
`token`	`String`	Unique. The session token. The mobile app sends it as a bearer token.
`expiresAt`	`DateTime`	Expiry. `session.expiresIn` is `config.sessionCookieMaxAge`, 30 days, in `packages/auth/src/config.ts`.
`userId`	`String`	Owner. Cascade delete.
`ipAddress`, `userAgent`	`String?`	Captured at sign-in.
`impersonatedBy`	`String?`	Admin user id when the admin plugin is impersonating.
`activeOrganizationId`	`String?`	The organization this session is working in. The organization plugin sets it.
`createdAt`, `updatedAt`	`DateTime`

Indexes: unique token, index on userId.

`Account`

Table auth.account. One row per sign-in method of a user.

Field	Type	Meaning
`accountId`	`String`	The id at the provider. For credential accounts it is the user id.
`providerId`	`String`	For example `credential` or `google`.
`userId`	`String`	Owner. Cascade delete.
`password`	`String?`	Password hash for credential accounts.
`accessToken`, `refreshToken`, `idToken`	`String?` (`@db.Text`)	OAuth tokens for social accounts.
`expiresAt`, `accessTokenExpiresAt`, `refreshTokenExpiresAt`	`DateTime?`	Token expiries.
`scope`	`String?`	Granted OAuth scopes.
`createdAt`, `updatedAt`	`DateTime`

Index on userId. Account linking trusts google and github as providers (trustedProviders in auth.ts). Google is the only social provider configured under socialProviders.

`Verification`

Table auth.verification. Short-lived values better-auth needs to check later: magic link tokens, email OTP codes, phone OTP codes, password reset tokens.

Field	Type	Meaning
`identifier`	`String`	What is being verified, for example an email or phone number with a purpose prefix. Indexed.
`value`	`String` (`@db.Text`)	The code or token, or a structure holding it and the attempt count.
`expiresAt`	`DateTime`	Expiry.
`createdAt`, `updatedAt`	`DateTime?`

`Passkey`

Table auth.passkey. WebAuthn credentials from the passkey() plugin.

Field	Type	Meaning
`name`	`String?`	Label the user gave the passkey.
`publicKey`	`String`	Credential public key.
`userId`	`String`	Owner. Cascade delete.
`credentialID`	`String`	WebAuthn credential id. Indexed.
`counter`	`Int`	Signature counter.
`deviceType`	`String`	Single-device or multi-device.
`backedUp`	`Boolean`	Whether the credential is synced.
`transports`	`String?`	Comma-separated transports.
`aaguid`	`String?`	Authenticator model id.
`createdAt`	`DateTime?`

Indexes on userId and credentialID.

`TwoFactor`

Table auth.twoFactor.

Field	Type	Meaning
`secret`	`String`	TOTP secret. Indexed.
`backupCodes`	`String`	Encoded backup codes.
`userId`	`String`	Owner. Cascade delete. Indexed.

Perform wraps the plugin in twoFactorWithOtpLanes (packages/auth/src/plugins/two-factor-otp-lanes.ts).

`Organization`

Table auth.organization. One row per studio account. The domain twin is Studio.

Field	Type	Meaning
`name`	`String`	Studio name as entered at signup.
`slug`	`String?`	Unique. Used in the web app URL. Slugs in `config.organizations.forbiddenOrganizationSlugs` are refused because they collide with top-level routes (`admin`, `settings`, `sign` and others).
`logo`	`String?`	Logo URL.
`metadata`	`String?`	Serialized JSON that better-auth stores as text.
`code`	`String?`	Unique. An optional short code for the organization.
`paymentsCustomerId`	`String?`	Payment provider customer id. Written by `setCustomerIdToEntity` in `packages/payments/src/lib/customer.ts` when the first subscription or order webhook arrives.
`createdAt`	`DateTime`

Relations: members, invitations, purchases. All cascade on organization delete. The beforeDeleteOrganization hook calls beforeOrganizationDelete (packages/auth/src/lib/deletion-hooks.ts) before the row goes.

`Member`

Table auth.member. Membership of a user in an organization.

Field	Type	Meaning
`organizationId`	`String`	Cascade delete.
`userId`	`String`	Cascade delete.
`role`	`String`	`owner`, `admin` or `member`. `isOrganizationAdmin` in `packages/auth/src/lib/helper.ts` treats `owner` and `admin` as admins, and so does a platform `User.role` of `admin`.
`createdAt`	`DateTime`

Unique on (organizationId, userId). Indexes on each column.

`Invitation`

Table auth.invitation. Pending staff invites.

Field	Type	Meaning
`organizationId`	`String`	Cascade delete.
`email`	`String`	Invitee. Indexed.
`role`	`String?`	Role granted on acceptance.
`status`	`String`	better-auth invitation status, for example `pending`, `accepted`, `rejected`, `canceled`.
`expiresAt`	`DateTime`
`inviterId`	`String`	The user who sent it. Cascade delete.
`createdAt`	`DateTime`	Default `now()`.

sendInvitationEmail sends the organizationInvitation template with a link to /login if the email already has a user, or /signup otherwise, carrying invitationId and email as query parameters. Pending invitations count toward the team seat limit. See Billing models. The plugins enabled in auth.ts decide which rows get written:

Method	Plugin	Rows touched
Email and password	core	`User`, `Account` (`credential`), `Session`
Google	`socialProviders.google`	`User`, `Account` (`google`), `Session`
Magic link	`magicLink()`	`Verification`, then `Session`
Phone OTP over WhatsApp	`phoneNumber()` with `sendLoginOtpOverWhatsapp`	`Verification`, `User.phoneNumber`, `Session`
Email OTP	`emailOTP()` with `disableSignUp: true`	`Verification`, then `Session`
Passkey	`passkey()`	`Passkey`, `Session`
Two-factor	`twoFactorWithOtpLanes`	`TwoFactor`
Username	`username()`	`User.username`

The delivery side of the OTP and email methods is covered in SmartSend WhatsApp and Email.

Coach web notifications

Two more auth models belong to the web app’s in-app notification bell. They are documented with the other notification tables in Messaging and notifications: Notification and UserNotificationPreference, with the enums NotificationType and NotificationTarget.

​How auth rows link to domain rows

​User

​Session

​Account

​Verification

​Passkey

​TwoFactor

​Organization

​Member

​Invitation

​Sign-in methods

​Coach web notifications

How auth rows link to domain rows

`User`

`Session`

`Account`

`Verification`

`Passkey`

`TwoFactor`

`Organization`

`Member`

`Invitation`

Sign-in methods

Coach web notifications