Core Concepts

Entity Model

application (SaaS service)
  │
  ├── oauth_client (OAuth protocol credentials)       1:1
  ├── sso_group_app ← sso_group (login sharing group) M:N
  │
  ├── application_user (user membership in app)      1:N
  │     └── user (global identity)                   M:1
  │
  ├── application_invitation (invitations)           1:N
  │
  └── application_api_key (M2M keys)                1:N

Application

A registered SaaS service. Each application has a unique audience (used as the JWT aud claim), its own auth_policy (account rules), and its own OAuth client credentials. Every application in the system is a tenant of the identity layer. Example values: tobby, studio, gamma.

Global User

A record in the Better Auth user table. One human, one identity, shared across all applications. A user exists globally as soon as they authenticate through any application. The user table has no app_id — identity is universal.

Application User

An explicit membership record linking a global user to a specific application. Each membership has its own status, role, and profile. A user can be active in Acme, pending_approval in gamma, and have no membership at all in Beta — all at the same time.

The membership is the key abstraction for per-application account control. It is created during signup (controlled by the policy engine) and its status is checked on every signin.

Auth Policy

A JSON document stored on every application that defines the account rules for that application:

• allowed_providers — which login methods are available
• signup_policy — how users can register (open, invite_only, etc.)
• password_policy — password complexity requirements
• session_policy — session lifetime and concurrency limits
• email domain rules — whitelist/blacklist for registration emails
• required profile fields — fields users must fill during registration

SSO Group

A set of applications that share login sessions. Applications in the same SSO group have a common parent domain and share cookies. A user who logs into one application in a group is automatically recognized by all others in the same group.

Applications not assigned to any group are isolated. They cannot share sessions with any other application.

Invitation

A token-bound invitation for a specific email address to join an application. Required when the application’s signup policy is set to invite_only. Invitations have expiration dates and status tracking (pending, accepted, expired, cancelled).

API Key

A machine-to-machine credential that allows a SaaS backend to authenticate directly to saas-core. API keys are hashed in the database. The plaintext key is shown once at creation time.

Naming Convention

Concept	Database (snake_case)	Drizzle (camelCase)	File/Module
SaaS service	application	application	application
User membership	application_user	applicationUser	membership
Invitation	application_invitation	applicationInvitation	invitation
M2M key	application_api_key	applicationApiKey	api-key
SSO group	sso_group	ssoGroup	sso-group