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#
| Field | Location | Value | Purpose |
|---|---|---|---|
UserDB.uid | users table, uid column | SuperTokens user ID (string) | Auth identity; mirrors Session.getUserId() |
UserDB.id | users table, id column (PK) | Internal UUID | Agenta 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:
- Obtain the SuperTokens session —
get_session(request)extracts the session from thesAccessTokencookie (or Authorization header). - Read the SuperTokens user ID —
session.get_user_id()returns the SuperTokens-assigned identity (=UserDB.uid). - Resolve via email — The backend fetches the SuperTokens user record, extracts
emails[0], then looks up the Agenta database row by email . - Set request state —
request.state.user_idis populated withstr(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_idis alwaysUserDB.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/wderives its scope fromSession.getUserId()and both must agree.user.id(internal UUID) — used in data queries and organization ownership checks, e.g., matchingorg.owner === user.idinorg.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.uidagainst the SuperTokens dashboard user ID for the affected account. - A
uid = "0"value indicates the row predatesuidpopulation and may cause local-storage namespacing failures on/m.
Key Files#
| File | Role |
|---|---|
api/oss/src/services/auth_helper.py | Session → Agenta user resolution pipeline |
api/oss/src/models/db_models.py | UserDB model (id, uid fields) |
api/oss/src/routers/user_profile.py | Profile endpoint returning both id and uid |
web/oss/src/lib/Types.ts | Frontend User interface |
web/oss/src/contexts/org.context.tsx | Uses user.id for ownership checks |