Auth Sessions Schema

Phase scope: [app]. This page describes session rows that attach the drafting browser/user session to the unified documents / documentVersions model.

Purpose

• Anchors a single drafting session: which document, which agent thread, which browser, and which user (once verified).
• Handles authorization state as one phase of the session's life — the name authSessions is historical; for most of the record's existence (pre-auth drafting, post-auth drafting, completion) auth is not the active concern.
• Links an access/authentication window to the authenticated user and the document being drafted.
• Supports resume flows across multiple visits.
• Stores agentThreadId to link this session to a Convex Agent thread (owned by the Agent component).

Relationships

• Many auth sessions can belong to one documents row.
• A session stores the current documentVersionKey when the session needs to resume or generate against an exact committed snapshot.
• An auth session authenticates one USERS record (the platform user operating the app, not a document subject).
• An auth session links to one Agent thread via agentThreadId.

Notes

• authSessions stores access and verification state only — not the conversation itself.
• Conversation history (threads and messages) is owned by the Convex Agent component in its own namespace.
• A document can have multiple auth sessions over time; each session references its Agent thread by ID.
• userId is typically set mid-interview, when the interview reaches a module with type: auth and the provider challenge succeeds. It is not required at session creation. See Auth Flow.
• A single users record may own many authSessions across many documents — a user drafts for themselves, a spouse, or multiple clients, and each draft gets its own session/document pair.
• documentKey may be set while status is still pending_auth, but a session opens the Document it names only once authorized — the binding rule refuses every other status (Auth Flow, GB-171). authSessions and the Document Folio are deliberately separate records.
• documentVersionKey should point at the latest committed version for resume/generation flows. During a transient editing window it can lag behind uncommitted client draft state; the runtime-persistence follow-up decides the transient buffer policy.

Fields

Example document

{
  "authSessionId": "SESS-00123",
  "status": "authorized",
  "userId": "user_01HV8XQZK4J9R9W3M6T4M2RUS1",
  "documentKey": "doc_01HV8XQZK4J9R9W3M6T4M2R8E1",
  "documentVersionKey": "docv_01HV8XQZK4J9R9W3M6T4M2RH09",
  "authProvider": "workos",
  "authChallengeId": "magic_auth_01HXYZ...",
  "authorizedAt": "2026-04-17T09:04:12Z",
  "authFailureReason": null,
  "agentThreadId": "m571x455qzv1f8ya42k32a5kcs852n7d",
  "browserClientId": "bc_01HXYZABCDEFGHJKMNPQRSTVWX",
  "routeKey": "simple_will-01HV8XQZK4J9R9W3M6T4M2R8E1"
}

Indexes

Foreign Keys

• authSessions.documentKey → documents.key (optional until document selection/creation).
• authSessions.documentVersionKey → documentVersions.key (optional until the first committed version exists).
• authSessions.userId → users.key or provider user identifier, depending on the users-table implementation.
• authSessions.agentThreadId → Convex Agent thread id (external Agent component namespace).