Authentication & Onboarding

A complete guide to user access flows: email registration, OTP verification, sign-in, OAuth, first-time onboarding, and the related security and localization behavior.

Email and password

The app supports first-class local registration and sign-in with a clear email-verification flow rather than treating local accounts as second-class citizens.

OTP verification

New users verify their email with an OTP before continuing. That reduces junk accounts and makes invitation flows more trustworthy.

Social login and onboarding

Google/GitHub can bring users into the product faster, but the app still keeps onboarding as a gate to decide whether they should enter the main workspace or complete first-time setup first.

Email registration and verification

Data Explorer’s local auth is designed to stand on its own rather than depend on OAuth. New users register with a name, email, and password; if the account is still unverified, the UI switches immediately into OTP verification instead of letting them stumble into deeper flows first.

Successful registration does not mean immediate access

After registration, the app may return an “unverified” state to force the OTP step. This is intentional behavior, not a failure.

Resend OTP is a supported recovery path

Users can request a new code without recreating the account. This matters in real-world mail delays and spam-folder scenarios.

Google, GitHub, and callback flows

Social login is not just a decorative button. It is a real backend route that exchanges an OAuth code for tokens and only then hydrates user state on the client. After that, the app still checks onboarding before deciding the final route.

What matters when configuring callback URLs

The callback URL must point to the real backend, not a fake frontend route. That is where the provider returns the code so the backend can exchange it for tokens and create a valid app session.

Session, onboarding, and user state

Tokens are only the starting point

After a successful login, the app still hydrates the user and supporting state such as connections so the workspace opens with meaningful context.

Onboarding is separate from auth

A successful login does not automatically mean the user should land on the main workspace. If `isOnboarded` is still incomplete, the app redirects into onboarding first.

Localization and system emails

Authentication is not only localized in the UI. The system also localizes server-side error messages, verification mail, password-reset mail, security alerts, and other templates. That matters when the product serves teams with different default languages.

Auth environment variables you should verify

Core auth envs

# Core security

JWT_SECRET=replace-with-a-random-secret-at-least-32-bytes-long

REFRESH_TOKEN_SECRET=another-very-long-secret

ENCRYPTION_KEY=12345678901234567890123456789012

# OAuth providers

GOOGLE_CLIENT_ID=...

GOOGLE_CLIENT_SECRET=...

GOOGLE_CALLBACK_URL=http://localhost:3001/api/auth/google/callback

GITHUB_CLIENT_ID=...

GITHUB_CLIENT_SECRET=...

GITHUB_CALLBACK_URL=http://localhost:3001/api/auth/github/callback

# Mail used for OTP / reset / verify

MAIL_USER=your-email@example.com

MAIL_PASS=your-provider-key

Authentication is a sensitive layer: a bad callback URL, weak JWT secret, or missing mail configuration can turn the experience into “registration works, but nobody can actually enter the app.” In production, verify both local and social auth end-to-end.

PreviousTeam Workspace Next Billing & Subscription

Ready to explore data?

Join the community on GitHub to contribute to the smartest local database IDE.

Launch App