Dosu LogoDosu Logo
Ask
Join our Discord
agentaPublic
Agenta
Documentsagenta
SuperTokens User Identity
SuperTokens User Identity
Type
Topic
Status
Published
Created
Oct 3, 2026
Updated
Oct 3, 2026

SuperTokens User Identity#

Agenta uses SuperTokens for session management, but each authenticated request ultimately resolves to two distinct user identifiers that serve different roles in the system. Confusing them—especially for migrated or legacy accounts—has historically caused routing bugs and inconsistent per-user preference storage.


The Two Identifiers#

FieldLocationValuePurpose
UserDB.uidusers table, uid columnSuperTokens user ID (string)Auth identity; mirrors Session.getUserId()
UserDB.idusers table, id column (PK)Internal UUIDAgenta database row identity

UserDB is defined in api/oss/src/models/db_models.py. Both fields are exposed by the profile endpoint , and the frontend User interface declares both as id and uid.


How a Session Maps to an Application User#

The backend authentication pipeline in api/oss/src/services/auth_helper.py performs this multi-step resolution on every authenticated request:

  1. Obtain the SuperTokens session — get_session(request) extracts the session from the sAccessToken cookie (or Authorization header).
  2. Read the SuperTokens user ID — session.get_user_id() returns the SuperTokens-assigned identity (= UserDB.uid).
  3. Resolve via email — The backend fetches the SuperTokens user record, extracts emails[0], then looks up the Agenta database row by email .
  4. Set request state — request.state.user_id is populated with str(user.id) — the internal UUID, not the SuperTokens ID .

The resolved UserDB.id is subsequently used in all downstream service calls. The mapping is cached by session ID to avoid repeated SuperTokens lookups .

Key point: The backend's request.state.user_id is always UserDB.id (UUID). The SuperTokens identity (UserDB.uid / Session.getUserId()) is only used as a lookup key during this resolution step — it does not propagate into the rest of the application.


Frontend: user.id vs user.uid#

On the frontend, both identifiers are available from the profile API. Their intended uses differ:

  • user.uid (SuperTokens ID) — used as the per-user preference scope key in local storage (e.g., agenta:onboarding:<uid>:…). This ensures that the same physical user is identified consistently across both the /w (desktop) and /m (mobile) app surfaces, because /w derives its scope from Session.getUserId() and both must agree.
  • user.id (internal UUID) — used in data queries and organization ownership checks, e.g., matching org.owner === user.id in org.context.tsx.

PR #6642 corrected /m's activeUserIdAtom to source from user?.uid instead of user?.id. Before the fix, /m namespaced local-storage preferences under the database UUID while /w used the SuperTokens UID, making one user appear as two different storage identities across surfaces.


Migrated / Legacy Users#

UserDB.uid defaults to "0" . Users created before the uid column was populated (migrated accounts) may have uid = "0" rather than their actual SuperTokens ID, whereas their id (UUID) and email are always set.

PR #6648 clarified that UserDB.uid is the SuperTokens ID — uid and Session.getUserId() are intended to agree. Any divergence for legacy accounts is a data migration gap, not an architectural difference. When debugging identity issues on self-hosted deployments:

  • Check UserDB.uid against the SuperTokens dashboard user ID for the affected account.
  • A uid = "0" value indicates the row predates uid population and may cause local-storage namespacing failures on /m.

Key Files#

FileRole
api/oss/src/services/auth_helper.pySession → Agenta user resolution pipeline
api/oss/src/models/db_models.pyUserDB model (id, uid fields)
api/oss/src/routers/user_profile.pyProfile endpoint returning both id and uid
web/oss/src/lib/Types.tsFrontend User interface
web/oss/src/contexts/org.context.tsxUses user.id for ownership checks
Documents
Agent Provider Authentication Errors
Channel Inbound Media Pipeline
Classic Mode Routing
Credential and Secrets Management
Evaluation Playground State Isolation
Evaluation Run Management
Hermes Harness Integration
Runner OTLP Trace Export Authentication
Sandbox Infrastructure
Session Interactions
Session Pool Management
SuperTokens User Identity
Testset Revision Semantics
Trace Drawer Deep Linking