Identity, onboarding, and workspace membership
Identity and workspace membership control who can enter a workspace and what that person can do there. The system turns sign-in or invitation into a user, a workspace membership, a workspace member profile, and a protected session context that the CRM uses for ownership, assignment, and record access. See CRM workspace domain and client application shell for the related workspace and client behavior.
Identity and session access
Identity is the account-level part of access. A user has one account identity and can belong to more than one workspace. Sign-in verifies that identity and then resolves the workspace where the user can continue.
The authentication flow supports these entry paths:
- Email and password sign-in and sign-up.
- Account-first sign-up without a workspace when instance policy allows it. The user can then choose an available workspace or create one.
- Email verification before password access when verification is required.
- Google and Microsoft sign-in.
- Workspace SSO through OIDC or SAML identity providers.
- One-time login and two-factor checks when the workspace requires them.
- Password reset and session renewal for an existing user.
- OAuth authorization for registered applications after the user has entered a workspace.
Email verification is a separate handoff in the sign-up path. A verification link can finish on the central domain or on a workspace domain. The flow keeps the user outside the workspace until the link is valid and the next session handoff succeeds.
The client separates account access from workspace choice. A user with no available workspace can create one when instance policy allows it. A user with one workspace enters it directly. A user with several workspaces chooses one before the client loads its member and permission state. The global picker combines workspaces available for sign-in and sign-up, while a maintenance or creation lock can hide workspace creation. Account-first sign-up is also subject to policy: a restricted instance can require an invitation or another provisioned destination before it creates a user without a workspace.
The server keeps the active session in a protected cookie. Login-token, email-verification, and SSO-exchange flows move a verified identity between authentication pages and workspace domains. The client records that the cookie session is active because browser code cannot read the cookie. Each new active session rotates a session generation marker so other client state can detect an identity change.
This diagram shows how an identity becomes a workspace session.
flowchart LR
A[Sign-in or sign-up] --> B{Verification or second factor?}
B -->|Yes| C[Complete the required check]
B -->|No| D[Resolve available workspaces]
C --> D
D --> E{Workspace count}
E -->|None| F[Create a workspace]
E -->|One| G[Enter workspace]
E -->|Several| H[Choose a workspace]
F --> I[Establish cookie session]
G --> I
H --> I
I --> J[Load user, member, and access state]
Authentication providers
Authentication providers define how a user proves identity. Workspace settings can enable password, Google, Microsoft, OIDC, or SAML sign-in. Provider verification does not grant workspace access. The system still checks membership or a valid invitation after identity is known.
Workspace-scoped sign-in shows only providers that apply to that workspace. The global sign-in view can list the workspaces available to the account. Social sign-in carries the intended action, invitation context, and safe return context through the provider redirect so a callback can continue with workspace creation, workspace selection, or workspace entry. Google sign-in requires a verified provider email. OIDC carries the identity-provider and invitation state through state; SAML carries only validated invitation state through RelayState, while the identity provider comes from the callback path. The SAML assertion must contain a valid email, an assertion ID, and an unexpired bearer confirmation, and the assertion can be used only once. Microsoft sign-in can retry a bounded number of transient provider failures while preserving that state; other guard failures return the normal workspace-aware error path.
Email verification has a recovery path. The user can resend the message or change the email after a failed verification. SSO can verify an existing passwordless user because the identity provider already proved control of the email. The authentication shell shows legal links on global and workspace entry pages, and it can show a workspace SSO bypass only when policy allows it. Password and two-factor steps use focused screens, while workspace selection and creation use their own footer actions. New password sign-up requires at least eight characters.
Password sign-in checks that the account has a password method and that the password is valid. Workspace-origin login checks access before password validity for non-members, so it does not reveal whether a non-member supplied the right password. Authentication errors use stable codes that map to safe GraphQL and REST responses.
References: packages/…/SignInUpGlobalScopeForm.tsx• L127-264 packages/…/SignInUpWithCredentials.tsx• L37-143 packages/…/useSignInWithGoogle.ts• L7-23 packages/…/auth.service.ts• L130-247 packages/…/sign-in-up.service.ts• L138-163 packages/…/auth.exception.ts• L11-110 packages/…/EmailVerificationSent.tsx• L64-165 packages/…/FooterNote.tsx• L60-117 packages/…/SignInUpStandardContent.tsx• L37-69 packages/…/SignInUpPasswordField.tsx• L38-61 packages/…/auth.resolver.ts• L203-375 packages/…/auth.resolver.ts• L536-673 packages/…/sign-up-without-workspace.input.ts• L8-14 packages/…/microsoft-oauth.guard.ts• L34-103 packages/…/google.auth.strategy.ts• L52-103 packages/…/saml.auth.strategy.ts• L159-252 packages/…/sso-auth.controller.spec.ts• L120-177 packages/…/saml.auth.strategy.spec.ts• L101-275
Session state
Session state joins the authenticated user to the current workspace. The client keeps separate state for the user, the workspace, the workspace member, and the permissions attached to the user’s workspace membership. The current workspace state also carries workspace access and security settings needed by the active experience. A cookie-session marker drives the logged-in view because the client cannot inspect the protected cookie.
Sign-in, SSO exchange, workspace switching, sign-out, and impersonation replace this state as one transition. Sign-out clears identity, workspace, member, and workspace-permission data, including persisted values from older session state, then broadcasts the change to other tabs. It retries an interrupted server revoke only when no newer cookie session is active. This prevents stale records or permissions from appearing under another identity.
References: packages/…/useAuth.ts• L121-177 packages/…/useMarkSessionActive.ts• L8-17 packages/…/sessionGenerationStore.ts• L9-46 packages/…/clearSessionLocalStorageKeys.ts• L3-19 packages/…/PendingServerSignOutEffect.tsx• L11-41 packages/…/currentWorkspaceState.ts• L8-62 packages/…/currentUserWorkspaceState.ts• L5-20
Workspace authentication context
The server turns a protected request into one workspace authentication context. This context states whether the request acts as a user, an application, an API key, the system, or a user in a workspace that is still activating. It carries the workspace and the identity details that downstream permission and record checks need.
The request boundary prefers an API-key context when one exists. It otherwise builds a complete user context when the user, membership, and workspace member are available. It can build an application context for application access, a system context for trusted system work, or a pending-activation user context while a new workspace is still being prepared. The middleware then makes that context available to the request and to workspace-scoped work. A workspace-agnostic token carries only account identity until the user selects or creates a workspace; it is not itself a workspace authentication context.
This diagram shows how protected request data becomes an access context.
flowchart TD
A[Protected request] --> B{Principal available}
B -->|API key| C[API-key context]
B -->|User and member| D[User context]
B -->|Application| E[Application context]
B -->|User in pending workspace| F[Pending-activation context]
B -->|System| G[System context]
B -->|None| H[Unauthenticated error]
C --> I[Workspace-scoped checks]
D --> I
E --> I
F --> I
G --> I
References: packages/…/build-workspace-auth-context-from-request.util.ts• L14-61 packages/…/workspace-auth-context.type.ts• L6-66 packages/…/workspace-auth-context.middleware.ts• L11-26 packages/…/build-user-auth-context.util.ts• L6-32 packages/…/build-application-auth-context.util.ts• L6-20 packages/…/jwt.auth.strategy.ts• L108-214 packages/…/jwt.auth.strategy.ts• L319-329
Server-admin identity assertions
A server-admin identity assertion is an extra trust check for a protected server-admin workspace. When this policy is configured, a request must carry a signed assertion whose issuer, audience, expiry, signing key, and email match the authenticated user. The server fetches and caches the public signing keys, but incomplete policy configuration fails closed rather than leaving the workspace open.
This check sits after user identity is known and before server-admin workspace work continues. It limits privileged workspace access to requests issued by the trusted identity service without changing normal workspace membership rules. Session tokens remain valid only in the protected session cookie, not as bearer tokens.
References: packages/…/server-admin-identity-assertion.service.ts• L41-108 packages/…/server-admin-identity-assertion.service.ts• L127-170 packages/…/verify-identity-assertion.util.ts• L8-39 packages/…/are-identity-assertion-signing-keys-fresh.util.ts• L1-20
Login and SSO handoffs
The login token is a short-lived handoff from an authentication step to a workspace session. The server verifies its type, provider, workspace origin, email state, membership or invitation, and any required second factor before it issues the protected session.
The SSO exchange token is a short-lived, single-use handoff for SSO sign-in that first reaches the root sign-in page. The client removes it from the URL and marks the cookie session active only after successful redemption. Invalid or already-used tokens leave the user outside the workspace. OIDC and SAML callbacks preserve personal invitation tokens as well as public invite context so SSO can finish the intended workspace entry.
Social sign-in can also carry a billing checkout session when the entry action starts or joins a workspace. This context identifies an optional plan, a billing interval, and whether a payment method is required. It remains part of the handoff and does not grant workspace access by itself.
References: packages/…/auth.service.ts• L385-427 packages/…/sso-exchange-token.service.ts• L24-113 packages/…/useVerifyLogin.ts• L20-35 packages/…/useRedeemSsoExchangeToken.ts• L11-50 packages/…/useSignInWithMicrosoft.test.ts• L22-81 packages/…/BillingCheckoutSession.ts• L1-10
Two-factor authentication
Two-factor authentication adds a workspace security check after the login token identifies the user and workspace. When setup is required, the user receives an authenticator setup value and submits a one-time code before the final session is issued.
The setup screen presents a QR value and lets the user copy the setup key before moving to code verification. If the authenticator cannot be used, an authorized workspace administrator can provide a recovery code. A valid recovery code resets the current authenticator and can return the user to setup. Missing tokens, invalid codes, and failed anti-bot checks keep the flow recoverable without creating partial access.
References: packages/…/TwoFactorAuthenticationProvisionEffect.tsx• L20-84 packages/…/SignInUpTwoFactorAuthenticationProvision.tsx• L38-85 packages/…/SignInUpTwoFactorAuthenticationVerification.tsx• L169-223 packages/…/SignInUpTwoFactorAuthenticationRecovery.tsx• L45-108 packages/…/auth.resolver.ts• L441-534
Impersonation sessions
Impersonation lets an authorized administrator enter another member’s workspace view without treating the target as a new account identity. The server checks both workspace relationships and administrator authority. The resulting context records that access is impersonated.
Stopping impersonation restores the original session when it is available. Otherwise the temporary view closes and the client signs out. Reload and session transitions clear user-scoped client data so the two identities do not mix.
References: packages/…/useImpersonationSession.ts• L11-86 packages/…/jwt.auth.strategy.ts• L126-177 packages/…/jwt.auth.strategy.ts• L249-317
Application authorization
Application authorization gives a registered external application short-lived access for a signed-in user and current workspace. The authorization page loads the application by client ID, explains the requested scopes, shows the workspace when one is active, and sends the user to the validated redirect host after consent. The server requires a real user session for consent and checks the application, redirect address, requested scope, and workspace before it returns the authorization result.
Public clients must use a PKCE code challenge. Registered redirects must pass URI checks, while clients without registered redirects can use loopback addresses for local apps. HTTPS is required for remote redirects, and a small set of desktop schemes is allowed for native app flows. The result can carry a validated issuer, resource, and caller state to the client.
Application tokens carry the workspace and application identity. They can also carry the user and user-workspace membership. Refresh renewal must match the active session’s workspace and application and must match the user and membership when those claims are present. Application access therefore extends workspace authority without replacing workspace membership.
References: packages/…/application-token.service.ts• L45-72 packages/…/application-token.service.ts• L209-242 packages/…/application-access-token-jwt-payload.type.ts• L4-13 packages/…/application-refresh-token-jwt-payload.type.ts• L4-11 packages/…/jwt.auth.strategy.ts• L332-428 packages/…/Authorize.tsx• L159-243 packages/…/Authorize.tsx• L291-364 packages/…/auth.resolver.ts• L1114-1128 packages/…/authorize-app.input.ts• L5-45 packages/…/auth.service.ts• L545-735 packages/…/is-loopback-hostname.util.ts• L7-26 packages/…/validate-redirect-uri.util.ts• L7-37 packages/…/is-loopback-hostname.util.spec.ts• L3-23
Invitation and workspace entry
An invitation is a time-limited grant to join one workspace. Members with the workspace-members permission can invite people by email, choose an assignable role, resend an invitation, remove it, or share a public invite link when that link is enabled.
An email invitation is tied to the invited email address. A valid invitation can add a new user or an existing user who is not yet a member. The system assigns the selected role or the workspace default role. After the user joins, the personal invitation is no longer usable.
Approved access domains can allow a matching email address to enter a workspace. A public link identifies a workspace but does not replace identity and access checks. A personal invitation is stronger because it binds entry to an email address.
This diagram shows the invitation paths and their shared membership result.
flowchart TD
A[Workspace member starts entry] --> B{Entry path}
B -->|Email invitation| C[Validate personal invitation]
B -->|Public link| D[Validate public invite policy]
B -->|Approved domain| E[Match email domain]
C --> F[Verify identity]
D --> F
E --> F
F --> G[Create user-workspace membership]
G --> H[Create workspace member profile]
H --> I[Assign role and load access state]
I --> J[Enter workspace]
Invitation sign-up
Invitation sign-up combines identity creation with workspace entry. The client keeps the personal invitation token or public workspace invite hash with the sign-up request. The same entry page changes its scope and title for a workspace invite, while a global page lets the user choose a workspace or create one. The server gives a personal invitation priority, checks the email and entry policy, verifies workspace readiness, and then adds the user.
New and existing users use the same access decision. A current member can continue to sign in, while a non-member needs a valid personal invitation, an enabled public link, or an approved access domain. A successful personal invitation is invalidated and can also prove control of the invited email. A new user who joins through the invitation receives the onboarding steps for that workspace.
References: packages/…/useSignInWithGoogle.ts• L7-23 packages/…/useWorkspaceFromInviteHash.ts• L17-75 packages/…/SignInUp.tsx• L96-142 packages/…/SignInUp.tsx• L144-211 packages/…/auth.service.ts• L197-234 packages/…/sign-in-up.service.ts• L177-243 packages/…/auth.resolver.ts• L601-673 packages/…/saml.auth.strategy.ts• L159-176
Invitation administration
The members settings area presents active invitations beside the team list. It exposes email invites, the public invite link, and approved email domains. The same invitation service supports onboarding and later member administration, so both paths share expiry, duplicate, role, and membership rules.
The invitation interface is protected by workspace-member permission. Choosing a role adds a second roles-permission check, and application access cannot silently grant the ability to manage invitations.
References: packages/…/workspace-invitation.resolver.ts• L38-58 packages/…/workspace-invitation.resolver.ts• L138-179 packages/…/SettingsWorkspaceMembersInviteTab.tsx• L126-244
Workspace membership and access
Workspace membership is the user’s relationship with one workspace. The account identity answers “who is this,” while the user-workspace membership answers “which workspace can this user enter.” The workspace member is the workspace-facing profile used by CRM records and relationships.
The membership path creates these related states:
| State | Purpose |
|---|---|
| User | Stores the account identity and account-wide status. |
| User-workspace membership | Connects the user to a workspace and carries membership permissions and security state. |
| Workspace member | Represents the user inside workspace records and CRM relationships. |
| Role assignment | Defines the member’s access to workspace features and records. |
Adding an existing user creates the membership and workspace member profile together. It then assigns a valid role and invalidates the personal invitation. A user who already belongs to the workspace is not added again. New members also consume an available workspace seat; a full workspace rejects the join before it creates the new user or membership.
References: packages/…/user.entity.ts• L31-126 packages/…/user-workspace.entity.ts• L37-107 packages/…/workspace-member.workspace-entity.ts• L54-81 packages/…/user-workspace.service.ts• L120-286 packages/…/sign-in-up.service.ts• L290-375
Roles and permissions
Roles turn membership into usable access. Workspace permission flags protect broad settings and actions. Object permissions control access to records through object metadata. The client displays the saved role and object permissions, but the server remains the authority for every protected action.
Workspace access and permission access are related but distinct. The active client workspace state carries broad permission flags and object record permissions keyed to object metadata, so the client can shape the workspace experience without becoming the server authority:
- Workspace access decides whether the user may enter the workspace.
- Permission access decides which settings, objects, and records the member may use after entry.
During workspace activation, the member receives a default permission view until the workspace is ready. The members settings page exposes team management only to members with the matching workspace permission. Role changes require the separate roles permission.
Record-level permissions can group field and relation checks into rules for each object. These rules refine record access after the member has entered the workspace, so they do not replace membership or workspace-entry checks.
References: packages/…/user.resolver.ts• L111-131 packages/…/workspace-invitation.resolver.ts• L161-179 packages/…/MemberPermissionsTab.test.tsx• L88-125 packages/…/currentUserWorkspaceState.ts• L5-20 packages/…/currentUserWorkspaceObjectRecordsPermissionsSelector.ts• L7-13 packages/…/buildRowLevelPermissionRulesInput.ts• L19-112 packages/…/upsertRowLevelPermissionRulesMutation.ts• L7-30
Member lifecycle
Membership has a clear lifecycle. A pending invitation becomes a membership only after a valid identity enters. Removing a member removes the workspace-facing relationship, transfers connected accounts and record shares when needed, and detaches related agent chat threads. Removing the last member suspends and deletes the workspace. Removing a user from their last workspace also removes the account identity.
The workspace member is a first-class CRM relationship. Tasks, companies, opportunities, timeline activity, and imported communication can refer to that member. Account email changes therefore propagate to the workspace member so identity and CRM ownership remain aligned.
References: packages/…/user.service.ts• L253-401 packages/…/update-workspace-member-email.job.ts• L11-47 packages/…/workspace-flat-workspace-member-map-cache.service.ts• L22-50 packages/…/workspace-member.workspace-entity.ts• L69-77 packages/…/workspace-member-delete-one.post-query.hook.ts• L45-143
Onboarding and access state
Onboarding is the per-user path that prepares a workspace for daily use. Its status is read in the context of both a user and a workspace, so two members of the same workspace can be at different steps. Workspace activation is part of this path because a new workspace must become ready before normal member entry and CRM use.
The status model covers these broad states:
| Status | Product meaning |
|---|---|
| Workspace activation | The workspace is still being created or made ready. |
| Sync email | The user may connect or skip a mail account. |
| Profile creation | The user completes the workspace-facing profile. |
| Invite team | The workspace creator can invite teammates. |
| Book call or plan required | The workspace must complete a commercial step when enabled. |
| Completed | The user can proceed to the normal workspace experience. |
The server derives the current status from workspace activation, per-user onboarding values, and billing state. The client advances the user after each step and keeps reversible history where the product allows it. The final step follows the active billing and booking rules rather than a fixed screen.
References: packages/…/onboarding-status.enum.ts• L1-9 packages/…/onboarding.service.ts• L108-196 packages/…/OnboardingStatusOrder.ts• L3-11 packages/…/useSetNextOnboardingStatus.ts• L21-77 packages/…/getNextOnboardingStatus.ts• L13-56
Profile setup
Profile setup completes the workspace-facing member profile during onboarding. The member can add a profile picture through the same workspace member record that later appears in CRM ownership and assignment views.
The upload first stores the picture and then updates the member’s avatar setting. The client refreshes its current member state only after both steps succeed, while an error leaves the existing profile state in place and reports the failure to the user.
References: packages/…/OnboardingProfilePictureUploader.tsx• L22-72 packages/…/OnboardingProfilePictureUploader.tsx• L74-109 packages/…/useUploadWorkspaceMemberProfilePicture.ts• L1-80 packages/…/useUpdateWorkspaceMemberSettings.ts• L1-80
Workspace activation
Workspace activation separates workspace creation from workspace use. A new workspace starts in a pending state while its shared data is prepared. The creator remains in the activation step until the workspace is ready, while existing members can still be recognized in supported transitional cases. Workspace creation is a user-session action, not an application-only action, although a signed-in application flow may act only when it includes a user.
New users cannot join an incomplete workspace. Protected user and permission reads refresh a pending workspace before deciding whether normal workspace data is available. Workspace creation requires an authenticated user session and a workspace-creation anti-bot check. The creation request can carry a display name, subdomain, and partner attribution, while an optional logo is uploaded after the workspace is created. Creation also remains subject to instance policy, subdomain rules, and workspace limits. The creation form requires a workspace name, checks subdomain availability when multi-workspace mode is enabled, and offers available subdomain alternatives when the requested address is taken.
Account-first sign-up creates only the user until the user selects or creates a workspace. The server allows that path only when instance policy permits a user without a workspace or when the user has a provisioned destination such as an invitation. This avoids creating accounts that cannot reach any workspace.
References: packages/…/sign-in-up.service.ts• L245-281 packages/…/sign-in-up.service.ts• L422-552 packages/…/sign-in-up.service.ts• L640-855 packages/…/jwt.auth.strategy.ts• L179-214 packages/…/user.resolver.ts• L118-180 packages/…/auth.resolver.ts• L536-738 packages/…/sign-up-in-new-workspace.input.ts• L6-29 packages/…/sign-up-without-workspace.input.ts• L8-14 packages/…/SignInUp.tsx• L144-235 packages/…/useSignUpInNewWorkspace.ts• L37-105 packages/…/SignInUpGlobalScopeForm.tsx• L161-234 packages/…/SignInUpWorkspaceCreationForm.tsx• L135-213 packages/…/SignInUpWorkspaceCreationForm.tsx• L225-353
Team invitation onboarding
The invite-team step connects onboarding to membership growth. The creator can enter several email addresses, send invitations, or skip the step. Valid addresses are cleaned before submission. A successful invitation advances onboarding and can record an invite reward.
Optional onboarding actions expose a direct Skip control. The shared skip dialog offers the available rewarded actions and a clear “Skip anyway” path. This keeps optional team growth separate from the access state needed to enter the workspace.
References: packages/…/useInviteTeam.ts• L28-72 packages/…/useInviteTeam.ts• L153-235 packages/…/OnboardingSkipButton.tsx• L4-19 packages/…/OnboardingSkipDialog.tsx• L40-107 packages/…/OnboardingRewardMainButton.tsx• L17-61
Connected account onboarding
The connect-account step links a member’s external mail or calendar account to the workspace. A successful Google or Microsoft connection records the account for that member, creates the enabled communication channels, and starts related import work. Reconnection clears failed or archived state and resumes sync.
The connection must resolve both the user-workspace relationship and the workspace member that owns the account. It also requires the connected-account permission and the provider scopes needed for the enabled services. The authorization state binds the provider request to the workspace, connection provider, user, membership, requested scope, optional account being reconnected, and flow secret. Tokens are stored for the workspace account after the external provider grants them, so later CRM sync remains tied to the same member and workspace.
References: packages/…/connected-account-oauth.service.ts• L24-65 packages/…/create-connected-account.service.ts• L38-115 packages/…/google-apis.service.ts• L94-203 packages/…/auth.service.ts• L1112-1139 packages/…/app-oauth-state-jwt-payload.type.ts• L5-16
Connected account settings
Connected account settings provide the later path for configuring and maintaining the mail and calendar accounts that onboarding can start. Provider choices are shown only when enabled. A user can complete a pending setup, reconnect a provider, edit a manual IMAP/SMTP/CalDAV connection, disconnect credentials while keeping synced data, or delete the account and its synced data.
The settings area now groups these actions with app preferences. Installed app health checks report whether an app has the variables it needs and offer a path to fix them. A new health result replaces an old result only when it belongs to the latest check, so a slow response cannot overwrite newer state.
References: packages/…/SettingsAccountsListEmptyStateCard.tsx• L22-75 packages/…/SettingsAccountsRowDropdownMenu.tsx• L58-83 packages/…/useTriggerProviderReconnect.ts• L8-38 packages/…/useImapSmtpCaldavConnectionForm.ts• L65-233 packages/…/SettingsApplicationHealthCheckEffect.tsx• L10-23 packages/…/useRunApplicationHealthCheck.ts• L10-70 packages/…/SettingsApplicationHealthCheckBanner.tsx• L15-49 packages/…/SettingsLegacyAccountsRedirect.tsx• L4-16 packages/…/AppPreferencesPathByLegacyAccountsPath.ts• L3-19
Workspace setup assistance
Onboarding can offer product help after the workspace has enough context to use it. The client can show contact-import guidance, free-credit progress, plan choices, and an optional workspace setup chat. These surfaces explain progress or offer help; they do not grant access or change the onboarding status by themselves.
Plan choices are presented as selectable cards with plan terms, notes or badges, and optional detail. Free-credit progress combines workspace credit state with the current onboarding step, profile state, invite state, creator state, and plan requirements. Reward buttons show the value of an available action. The progress view can highlight new credit and respects reduced-motion preferences. A failed plan load or unavailable setup chat keeps a retry or normal workspace path available.
After enrichment finishes or a bounded 2.5-second wait ends, the client sends available company and person context to the chat service. The kickoff is guarded so it runs once for the onboarding session. If the user chose to open the chat, a returned thread is added to the inbox, its permissions are refreshed, and the client opens it. An unavailable result leaves the normal onboarding path available. A failed request clears the guard so the flow can retry.
References: packages/…/onboardingCreditsProgressSelector.ts• L18-50 packages/…/getOnboardingCreditsProgress.ts• L14-154 packages/…/OnboardingFreeCreditsPill.tsx• L112-157 packages/…/OnboardingFreeCreditsProgressBar.tsx• L102-147 packages/…/OnboardingRewardMainButton.tsx• L17-61 packages/…/OnboardingPlanCard.tsx• L110-169 packages/…/WorkspaceSetupChatKickoffEffect.tsx• L23-128 packages/…/WorkspaceSetupChatEnrichmentMaxWaitMs.ts• L1 packages/…/hasRequestedWorkspaceSetupChatState.ts• L1-6 packages/…/shouldOpenAiChatAfterOnboardingState.ts• L1-7 packages/…/companyEnrichmentState.ts• L1-14 packages/…/personEnrichmentState.ts• L1-14 packages/…/isCompanyEnrichmentFetchInFlightState.ts• L1-6 packages/…/ChooseYourPlanErrorState.tsx• L19-53
Access state transitions
Access state changes as the user moves between authentication, onboarding, and normal workspace use. The client uses the current onboarding status to decide whether to show a step or the CRM. The server recalculates that status from fresh workspace and user data.
When a user switches workspace, the client replaces the current workspace, member, and user-workspace state together. When a member is removed or a session is revoked, the next protected request must stop normal workspace use rather than continue with stale local state. Return paths are limited to safe internal application paths and cannot point back to unfinished authentication or onboarding flows.
References: packages/…/onboarding.service.ts• L120-196 packages/…/jwt.auth.strategy.ts• L150-214 packages/…/user.resolver.ts• L170-180 packages/…/useAuth.ts• L121-177 packages/…/useGoBackToPreviousOnboardingStep.ts• L15-68
Password recovery
Password recovery starts outside an authenticated workspace session. The client checks the email and anti-bot state and includes workspace context only when the page has it. The server rate-limits requests and returns a privacy-preserving success response without revealing whether the address exists. The client keeps the same safe success message whether a matching account exists, while it reports invalid input, an unavailable anti-bot check, or a request failure as an error.
References: packages/…/useHandleResetPassword.ts• L14-73 packages/…/useHandleResetPassword.test.ts• L76-167 packages/…/auth.resolver.ts• L1239-1293
Refresh scope
The refresh covers these status-tagged changes:
- { "path": "packages/twenty-front/src/modules/auth/sign-in-up/hooks/useSso.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/auth/states/currentWorkspaceState.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/onboarding/effect-components/WorkspaceSetupChatKickoffEffect.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/onboarding/effect-components/WorkspaceSetupChatSidePanelEffect.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsCalendarChannelsContainer.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsConnectedAccountsListCard.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsLegacySections.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsListEmptyStateCard.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsMessageChannelsContainer.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsRowDropdownMenu.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsSelectedMessageChannelEffect.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/SettingsAccountsSettingsSection.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/components/stories/SettingsAccountsRowDropdownMenu.stories.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/constants/SettingsAccountCalendarChannelsTabListComponentId.ts", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/constants/SettingsAccountMessageChannelsTabListComponentId.ts", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/hooks/tests/useTriggerProviderReconnect.test.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/hooks/useAccountsConfigurationCompletionPath.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/hooks/useImapSmtpCaldavConnectionForm.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/accounts/hooks/useTriggerProviderReconnect.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/components/SettingsAdminWorkspaceBillingArrangementDetailsModal.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/components/SettingsAdminWorkspaceBillingArrangementModal.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/components/SettingsAdminWorkspaceBillingArrangementRowDropdownMenu.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/components/SettingsAdminWorkspaceBillingArrangementsSection.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/components/SettingsAdminWorkspaceBillingContent.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/components/SettingsAdminWorkspaceUsageLimitModal.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/constants/BillingArrangementCommentMaxLength.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/constants/BillingArrangementSeatCapModeLabels.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/constants/BillingArrangementStatusTags.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/constants/BillingArrangementTypeLabels.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/constants/EndBillingArrangementDialogId.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/constants/SettingsAdminFeatureFlagMetadata.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/graphql/mutations/createWorkspaceBillingArrangement.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/graphql/mutations/endWorkspaceBillingArrangement.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/graphql/queries/workspaceBillingArrangements.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/states/adminPanelBillingArrangementIdPendingEndState.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/types/AdminBillingArrangement.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/tests/formatAdminBillingArrangementDetails.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/tests/formatAdminBillingArrangementEndDate.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/tests/formatAdminBillingArrangementOperator.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/tests/parseAdminBillingArrangementCreditAllowance.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/tests/parseAdminBillingArrangementSeats.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/formatAdminBillingArrangementDetails.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/formatAdminBillingArrangementEndDate.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/formatAdminBillingArrangementOperator.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/getAdminUsageLimitOperationLabel.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/getAdminUsageLimitPeriodLabel.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/getAdminUsageLimitResourceLabel.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/parseAdminBillingArrangementCreditAllowance.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/admin-panel/utils/parseAdminBillingArrangementSeats.ts", "status": "A" }
- { "path": "packages/twenty-front/src/pages/settings/ai/utils/getSettingsAiBreadcrumbLinks.ts → packages/twenty-front/src/modules/settings/ai/utils/getSettingsAiBreadcrumbLinks.ts", "status": "R" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/components/SettingsLegacyAccountsRedirect.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/components/stories/SettingsLegacyAccountsRedirect.stories.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/constants/AppPreferencesPathByLegacyAccountsPath.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/constants/MyApplicationHealthCheckRunner.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/graphql/mutations/runMyApplicationHealthCheck.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/hooks/tests/useAccountsSettingsBreadcrumbLink.test.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/hooks/useAccountsSettingsBreadcrumbLink.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/states/myApplicationHealthCheckFamilyState.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/utils/tests/getAccountGroupActionTargets.test.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/utils/tests/getAccountGroupApplicationsWithSettings.test.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/utils/tests/getApplicationsWithPreferences.test.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/utils/getAppPreferencesPathnameFromLegacyAccountsPathname.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/app-preferences/utils/getApplicationsWithPreferences.ts", "status": "M" }
- { "path": "packages/twenty-front/src/pages/settings/applications/components/SettingsApplicationHealthBanner.tsx → packages/twenty-front/src/modules/settings/applications/components/SettingsApplicationHealthBanner.tsx", "status": "R" }
- { "path": "packages/twenty-front/src/modules/settings/applications/components/SettingsApplicationHealthCheckBanner.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/components/SettingsApplicationHealthCheckEffect.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/components/SettingsApplicationsInstalledAppsSection.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/applications/components/stories/SettingsApplicationsInstalledAppsSection.stories.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/pages/settings/applications/components/tests/SettingsApplicationHealthBanner.test.tsx → packages/twenty-front/src/modules/settings/applications/components/tests/SettingsApplicationHealthBanner.test.tsx", "status": "R" }
- { "path": "packages/twenty-front/src/modules/settings/applications/constants/WorkspaceApplicationHealthCheckRunner.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/tests/useApplicationVariablesDraft.test.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/tests/useInstalledBuiltInAccountApp.test.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/tests/useInstalledBuiltInAccountApps.test.tsx", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/tests/useRunApplicationHealthCheck.test.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/useApplicationVariablesDraft.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/useInstalledBuiltInAccountApp.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/useInstalledBuiltInAccountApps.ts", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/useRunApplicationHealthCheck.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/useSaveApplicationVariablesAndRecheckHealth.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/hooks/useWorkspaceApplicationStatusesById.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/applications/states/workspaceApplicationHealthCheckFamilyState.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/types/ApplicationHealthCheckRunner.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/applications/types/ApplicationHealthCheckState.ts", "status": "A" }
- { "path": "packages/twenty-front/src/pages/settings/applications/utils/tests/getApplicationHealthBanner.test.ts → packages/twenty-front/src/modules/settings/applications/utils/tests/getApplicationHealthBanner.test.ts", "status": "R" }
- { "path": "packages/twenty-front/src/pages/settings/applications/utils/tests/getApplicationHealthBannerAppearance.test.ts → packages/twenty-front/src/modules/settings/applications/utils/tests/getApplicationHealthBannerAppearance.test.ts", "status": "R" }
- { "path": "packages/twenty-front/src/pages/settings/applications/utils/getApplicationHealthBanner.ts → packages/twenty-front/src/modules/settings/applications/utils/getApplicationHealthBanner.ts", "status": "R" }
- { "path": "packages/twenty-front/src/pages/settings/applications/utils/getApplicationHealthBannerAppearance.ts → packages/twenty-front/src/modules/settings/applications/utils/getApplicationHealthBannerAppearance.ts", "status": "R" }
- { "path": "packages/twenty-front/src/modules/settings/components/SettingsEnterpriseFeatureGateCard.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/components/SettingsListCard.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/components/SettingsNavigationDrawerItem.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/components/SettingsNavigationDrawerItems.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/components/SettingsSectionAnchor.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/components/SettingsSectionAnchorScrollEffect.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/components/stories/SettingsSectionAnchor.stories.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/components/layout/useSettingsActiveTabId.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/constants/SettingsSectionAnchorDataAttribute.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/data-model/object-details/components/SettingsObjectFieldItemTableRow.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/data-model/object-details/components/SettingsObjectRelationItemTableRow.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/developers/utils/tests/formatExpiration.test.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/developers/utils/formatExpiration.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/hooks/tests/useSettingsNavigationItems.test.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/hooks/useSettingsNavigationItems.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerDangerZone.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerDetail.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerEditForm.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerFormFields.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerFormLayout.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerLabelField.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerNewForm.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerStatus.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerTableRow.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerTextField.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerToolsSection.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServerToolsTable.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServersSection.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/SettingsMcpServersTable.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/components/stories/SettingsMcpServersTable.stories.tsx", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/constants/DeleteMcpServerDialogId.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/constants/McpServerFormDefaultValues.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/constants/McpServerTableBodyMaxHeight.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/constants/McpServerTableRowGridTemplateColumns.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/constants/McpServerToolTableBodyMaxHeight.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/constants/McpServerToolTableRowGridTemplateColumns.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/hooks/useCreateMcpServer.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/hooks/useDeleteMcpServer.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/hooks/useNavigateToMcpServersList.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/hooks/useSyncMcpServerTools.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/hooks/useUpdateMcpServer.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/utils/getMcpServerFormValues.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/utils/getMcpServerStatus.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/validation-schemas/tests/mcpServerFormSchema.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp-servers/validation-schemas/mcpServerFormSchema.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/mcp/components/SettingsMcpSetupCard.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/graphql/fragments/rowLevelPermissionPredicateFragment.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/graphql/fragments/rowLevelPermissionPredicateGroupFragment.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/graphql/hooks/useUpsertRowLevelPermissionPredicatesMutation.ts", "status": "D" }
- { "path": "packages/twenty-front/src/modules/settings/roles/graphql/hooks/useUpsertRowLevelPermissionRulesMutation.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/roles/graphql/mutations/upsertRowLevelPermissionPredicatesMutation.ts → packages/twenty-front/src/modules/settings/roles/graphql/mutations/upsertRowLevelPermissionRulesMutation.ts", "status": "R" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role-permissions/object-level-permissions/components/SettingsRolePermissionsObjectLevelSeeFieldsValueForObject.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role-permissions/object-level-permissions/components/SettingsRolePermissionsObjectLevelUpdateFieldsValueForObject.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role-permissions/object-level-permissions/record-level-permissions/hooks/useRecordLevelPermissionSyncToDraftRole.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role-permissions/object-level-permissions/record-level-permissions/utils/recordLevelPermissionPredicateConversion.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role-permissions/permission-flags/components/stories/SettingsRolePermissionsFlagSections.stories.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role/hooks/useSaveDraftRoleToDB.ts", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role/utils/tests/buildRowLevelPermissionRulesInput.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/roles/role/utils/buildRowLevelPermissionRulesInput.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/security/components/SettingsSecuritySettings.tsx", "status": "M" }
- { "path": "packages/twenty-front/src/modules/settings/utils/tests/watchSettingsSectionAnchorScroll.test.ts", "status": "A" }
- { "path": "packages/twenty-front/src/modules/settings/utils/watchSettingsSectionAnchorScroll.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/auth.exception.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/controllers/google-apis-auth.controller.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/controllers/microsoft-apis-auth.controller.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/controllers/sso-auth.controller.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/dto/get-authorization-url-for-sso.input.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/filters/auth-rest-api-exception.filter.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/guards/google-apis-oauth-exchange-code-for-token.guard.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/constants/identity-assertion-algorithms.constant.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/constants/identity-assertion-signing-keys-fetch-timeout-ms.constant.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/constants/identity-assertion-signing-keys-max-age-ms.constant.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/constants/identity-assertion-signing-keys-min-refetch-interval-ms.constant.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/services/server-admin-identity-assertion.service.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/types/identity-assertion-refusal-reason.type.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/types/identity-assertion-signing-key-set.type.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/tests/are-identity-assertion-signing-keys-fresh.util.spec.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/tests/get-identity-assertion-key-id.util.spec.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/tests/parse-identity-assertion-signing-keys.util.spec.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/tests/should-fetch-identity-assertion-signing-keys.util.spec.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/tests/verify-identity-assertion.util.spec.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/are-identity-assertion-signing-keys-fresh.util.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/get-identity-assertion-key-id.util.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/parse-identity-assertion-signing-keys.util.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/should-fetch-identity-assertion-signing-keys.util.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/identity-assertion/utils/verify-identity-assertion.util.ts", "status": "A" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/strategies/oidc.auth.strategy.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/strategies/saml.auth.strategy.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/token/services/access-token.service.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/token/token.module.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/auth/utils/auth-graphql-api-exception-handler.util.ts", "status": "M" }
- { "path": "packages/twenty-server/src/engine/core-modules/user/user.resolver.ts", "status": "M" }
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the user, user-workspace membership, and workspace member creation path aligned with seat checks. A missing state or a late seat check can leave a person authenticated but unable to use CRM ownership or assignment.
- Keep invitation validation aligned with invitation creation. Email binding, expiry, role selection, approved domains, and public-link behavior must match in sign-up and settings flows.
- Keep social sign-in action, invitation context, and billing checkout context—including optional plan, interval, and payment-method requirement—aligned across the sign-in button, provider redirect, and workspace entry path.
- Keep email verification failure actions aligned with the verification handoff. Resend and change-email paths must not create a session before verification succeeds.
- Keep account-first sign-up policy aligned with workspace availability. A user created without a workspace must have a valid path to choose or create one.
- Keep transient Microsoft OAuth retry state bounded and preserve the original workspace and action context across the retry.
- Keep the request-context precedence aligned with all supported principals. API keys, users, applications, system work, and pending-activation users must receive the context expected by downstream guards.
- Keep role assignment, workspace permission flags, and object record permissions aligned with the guards on member, role, and object settings.
- Keep application authorization claims aligned across client ID lookup, PKCE, redirect URI, requested scope, resource, issuer, authorization code, and consent display.
- Keep application refresh claims aligned with refresh checks. Application, workspace, user, and user-workspace membership must refer to the same active session when present.
- Keep loopback and custom redirect rules aligned with client registration. Local app redirects must remain limited to approved loopback hosts and allowed schemes.
- Keep connected-account ownership aligned across provider callbacks, the workspace member, and the user-workspace relationship. Account channels and imports must use the same workspace identity.
- Keep provider scopes, OAuth state claims, reconnect targets, and connected-account permission checks aligned. Workspace entry must not grant permission to connect a mail or calendar account.
- Keep onboarding status derivation aligned with the client’s next-step order and dynamic final-step rules.
- Keep onboarding credit progress aligned with free-credit state, onboarding configuration, user status, creator status, profile state, invite state, and plan requirements.
- Keep workspace activation rules aligned with sign-in, invitation, member reads, permission reads, and request-context construction. New users must not enter a workspace that is still being created.
- Keep workspace creation fields aligned with the creation contract. Authenticated session, anti-bot check, name, optional display name, partner attribution, logo, multi-workspace subdomain availability, and suggested alternatives must lead to one workspace and one activation state.
- Keep profile-picture upload, member avatar settings, file URLs, and current-member client state aligned. A successful upload must update the workspace member that onboarding is editing.
- Keep every authentication success path aligned with the cookie-session marker and session generation. A server session without the client marker can leave stale identity state visible.
- Clear or refresh session-scoped client state together when sign-out, workspace switching, member removal, session renewal, or impersonation changes the active identity. Include the current workspace permission state and older persisted session keys.
- Keep GraphQL and REST auth error mappings aligned with the shared auth error codes.
- Keep pending-workspace logo reservation and completion tied to the same workspace and member.
- Keep user-session-only account actions behind a user-session guard. An application token must not create a workspace or approve an application for a user.
- Keep setup-chat context and outcome values aligned between enrichment state, the mutation, and post-onboarding chat state. An unavailable result must remain optional.
- Keep application authorization display and consent aligned with the server contract. Client ID lookup, scope labels, workspace display, redirect handling, PKCE requirements, issuer, resource, and authorization errors must describe the same application access that the server grants.
- Keep SSO provider state aligned with invitation entry. OIDC
stateand SAMLRelayStatemust preserve only validated workspace invitation context, and the callback path must remain the source of the identity provider. - Keep server-admin identity assertion policy complete and fail-closed. The assertion header, issuer, audience, signing-key source, key freshness, allowed algorithms, expiry, and authenticated email must describe the same trusted identity service.
- Keep account settings paths aligned during the move to app preferences. Legacy account URLs must retain their query and hash while reaching the matching account, connection, or app-health view.
- Keep connected-account health checks tied to the latest run. Saving app variables must trigger a fresh check, and a late response must not replace a newer result.
- Keep record-level permission groups aligned with their object, field, relation, operation, and member predicates when role rules are saved.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A login or SSO handoff is missing, expired, or already consumed. | The user remains outside the workspace. | Validate token type and single-use state, and activate the client session only after successful exchange. |
| A password login targets an account without a password method or uses a wrong password. | The password path is rejected without treating a social-only account as password-authenticated. | Check the password method and value, and return stable auth errors. |
| Account-first sign-up is disabled and the user has no provisioned workspace destination. | The account is not created without a workspace it cannot reach. | Apply the instance policy before saving the new user. |
| A new-workspace request has no authenticated provider context. | Workspace creation is rejected before it can create a user or workspace. | Require a user session with a resolved authentication provider. |
| Workspace creation fails its anti-bot check or has invalid input. | The workspace is not created. | Check the workspace-creation captcha and validate display name, subdomain, partner, and related inputs. |
| A transient Microsoft OAuth failure exceeds the retry limit. | The user leaves the retry path and receives the provider error. | Preserve state only for bounded retries, then use the normal guard error redirect. |
| An invitation email does not match the email used at entry. | The recipient cannot join through that invitation. | Validate the personal invitation against the user email. |
| An invitation expires or is removed before use. | Sign-up or sign-in is denied. | Validate the invitation at entry and expose current state in settings. |
| A request has no usable authentication context. | Workspace-scoped work is rejected as unauthenticated. | Build context only from a valid API key, complete user membership, application, system, or pending-activation user. |
| A user token points to another workspace or user-workspace membership. | The request cannot use that workspace. | Resolve the membership and compare it with the token workspace. |
| An application refresh token belongs to another application, workspace, user, or membership. | The application cannot renew access for the current session. | Compare the application and workspace claims and compare user and membership claims when present. |
| An OAuth authorization request has no registered client, lacks PKCE for a public client, or uses an invalid redirect or scope. | The consent page cannot safely grant access or return the result. | Load the registration by client ID and validate PKCE, redirect URI, scope, issuer, and resource before redirecting. |
| A redirect uses a non-HTTPS remote host or an unapproved custom scheme. | Application authorization is rejected. | Allow HTTPS, approved loopback hosts, and the explicit native schemes only. |
| A connected-account callback has invalid workspace, membership, scope, or reconnect state. | The external account is not created or updated for the intended member. | Bind OAuth state to the workspace, user, membership, provider scope, and optional reconnect target. |
| A provider callback lacks the required mail or calendar permission. | The connected account is not usable and onboarding cannot complete. | Check provider scopes and service availability before creating channels. |
| A member lacks connected-account permission. | Account connection is refused even when identity and membership are valid. | Check the user-workspace relationship and connected-account setting permission. |
| Workspace activation remains pending during new-user entry. | New users cannot join the incomplete workspace. | Allow pending access only for the activation path and block new-member entry until ready. |
| A requested workspace subdomain is invalid or unavailable. | Workspace creation cannot continue with that address. | Require a valid available subdomain and offer alternatives when the address is taken. |
| Profile picture upload or member settings update fails. | The onboarding profile keeps its prior avatar and reports an upload error. | Update current member state only after both operations succeed, and surface the failure to the user. |
| Client workspace, member, or object-permission state remains after sign-out or workspace change. | The UI can show records or permissions from another identity. | Clear and reload session-scoped state as one transition and rotate the session generation. |
| A failed sign-out retry runs after a new cookie session exists. | The retry can revoke the new session. | Drop the retry when a newer active cookie session exists. |
| Billing plan loading or setup chat fails during onboarding. | Optional onboarding help cannot continue. | Keep retry and logout separate, and leave normal workspace entry available. |
| A SAML assertion is expired, lacks a bearer expiry, or has already been used. | SSO sign-in is rejected without creating a session. | Validate the assertion structure and expiry before consuming its ID, then consume it once. |
| A server-admin identity assertion is missing, invalid, stale, signed by an unknown key, or has a different email. | Access to the server-admin workspace is refused. | Require complete assertion configuration, fetch fresh trusted keys, verify issuer and audience, and compare the assertion email with the authenticated user. |
| A legacy account URL is not mapped to its app-preferences route. | A published link can open the wrong settings view or fail to reach account setup. | Preserve the legacy path map and carry search and hash values through the redirect. |
| A connected-account health response arrives after a newer check. | The settings view can show an old app status. | Store a run ID and accept a result only for the current run. |
| A role saves record-level predicates with the wrong object or group shape. | The member can receive the wrong record access. | Build each rule from its operation flags and nested predicate groups before saving it. |
Key files
| File | Why to read it |
|---|---|
| packages/…/auth.resolver.ts | Shows the public authentication entry points and the handoffs into sessions, workspace entry, account-first sign-up, workspace creation, recovery, and application authorization. |
| packages/…/auth.module.ts | Shows the authentication boundary and the workspace, invitation, onboarding, session, OAuth, and connected-account systems it coordinates. |
| packages/…/auth.service.ts | Shows the boundary between identity verification, workspace access, invitations, SSO, connected accounts, and application authorization. |
| packages/…/sign-in-up.service.ts | Shows how account-first sign-up, new workspace creation, existing workspace entry, and invitations become user and membership state. |
| packages/…/sign-up-without-workspace.input.ts | Defines the account-first sign-up contract and its optional partner context. |
| packages/…/microsoft-oauth.guard.ts | Shows the bounded retry and workspace-aware error path for Microsoft sign-in. |
| packages/…/google.auth.strategy.ts | Shows how Google identity and workspace entry context travel through the provider callback. |
| packages/…/jwt.auth.strategy.ts | Shows how protected requests resolve identity, workspace membership, activation state, applications, and impersonation. |
| packages/…/build-workspace-auth-context-from-request.util.ts | Shows how a protected request becomes a workspace authentication context. |
| packages/…/application-token.service.ts | Shows application token claims and session-bound refresh validation. |
| packages/…/application-refresh-token-jwt-payload.type.ts | Defines the application, workspace, and optional user membership claims used for application refresh. |
| packages/…/Authorize.tsx | Shows the application consent view, scope explanation, workspace label, safe redirect notice, and error path. |
| packages/…/authorize-app.input.ts | Defines the application authorization request, including redirect, scope, issuer, resource, and PKCE context. |
| packages/…/validate-redirect-uri.util.ts | Shows the safe URI rules used before an authorization result leaves the system. |
| packages/…/is-loopback-hostname.util.ts | Shows which local host forms are accepted for native application redirects. |
| packages/…/saml.auth.strategy.ts | Shows how SAML identity, invitation relay state, assertion freshness, and single-use checks enter the SSO flow. |
| packages/…/oidc.auth.strategy.ts | Shows how OIDC identity and invitation state enter the SSO callback. |
| packages/…/server-admin-identity-assertion.service.ts | Shows the extra signed-identity check for the server-admin workspace. |
| packages/…/verify-identity-assertion.util.ts | Shows the accepted assertion claims and signature checks. |
| packages/…/access-token.service.ts | Shows session-token source checks and the point where server-admin identity assertions protect requests. |
| packages/…/SettingsAccountsRowDropdownMenu.tsx | Shows the account setup, reconnect, disconnect, and delete choices in settings. |
| packages/…/useImapSmtpCaldavConnectionForm.ts | Shows the manual external-account connection path. |
| packages/…/useRunApplicationHealthCheck.ts | Shows how installed app health state is refreshed without accepting stale results. |
| packages/…/AppPreferencesPathByLegacyAccountsPath.ts | Shows the compatibility map from old account URLs to app-preferences routes. |
| packages/…/buildRowLevelPermissionRulesInput.ts | Shows how record-level predicates become saved role rules. |
| packages/…/upsertRowLevelPermissionRulesMutation.ts | Shows the contract for saving record-level rules and predicate groups. |
| packages/…/app-oauth-state-jwt-payload.type.ts | Defines the workspace, membership, provider, scope, and reconnect context carried through connected-account callbacks. |
| packages/…/connected-account-oauth.service.ts | Shows the membership and permission boundary for external account connection. |
| packages/…/google-apis.service.ts | Shows how provider scopes become connected accounts, channels, and import work. |
| packages/…/workspace-invitation.resolver.ts | Shows the protected interface for invitation management and role assignment. |
| packages/…/user.resolver.ts | Shows current-user loading, workspace activation refresh, and permission state. |
| packages/…/workspace-member-delete-one.post-query.hook.ts | Shows the cleanup and ownership transfers that follow member removal. |
| packages/…/onboarding.service.ts | Shows how workspace readiness and per-user progress become onboarding state. |
| packages/…/useAuth.ts | Shows client sign-in, workspace selection, cookie-session state, sign-out, and workspace transitions. |
| packages/…/currentWorkspaceState.ts | Shows the workspace data kept with the active client session, including access and security settings. |
| packages/…/currentUserWorkspaceState.ts | Shows the active workspace permission state, security summary, impersonation state, and object record permissions. |
| packages/…/currentUserWorkspaceObjectRecordsPermissionsSelector.ts | Shows how the client reads object record permissions from the active workspace state. |
| packages/…/clearSessionLocalStorageKeys.ts | Shows which identity, workspace, member, permission, and legacy session values are cleared together. |
| packages/…/useSignUpInNewWorkspace.ts | Shows the client contract for captcha-protected workspace creation, logo upload, and login-token handoff. |
| packages/…/SignInUpGlobalScopeForm.tsx | Shows account-level provider choice, workspace selection, and workspace-creation policy in the global sign-in view. |
| packages/…/SignInUpWithCredentials.tsx | Shows the email, password, sign-in, sign-up, and maintenance-lock steps. |
| packages/…/SignInUpWorkspaceCreationForm.tsx | Shows the workspace creation inputs for name, optional logo, and available subdomain. |
| packages/…/EmailVerificationSent.tsx | Shows the recovery actions around email verification before workspace entry. |
| packages/…/SignInUpTwoFactorAuthenticationProvision.tsx | Shows the setup handoff from authenticator enrollment to one-time-code verification. |
| packages/…/useSignInWithGoogle.ts | Shows how invitation and action context travels through social sign-in. |
| packages/…/BillingCheckoutSession.ts | Defines the billing context that can travel with workspace entry. |
| packages/…/OnboardingProfilePictureUploader.tsx | Shows how onboarding updates the workspace member profile picture and current member state. |
| packages/…/useInviteTeam.ts | Shows how onboarding team invitations validate addresses, send invites, and advance progress. |
| packages/…/OnboardingSkipDialog.tsx | Shows the shared skip-and-reward choice for deferrable onboarding actions. |