Authentication & OTP Flow
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau utilizes an OTP-first (One-Time Password) authentication system powered by Supabase Auth. This flow eliminates traditional passwords in favor of 6-digit verification codes sent via email, supporting both user login and registration within a unified interface. The system is designed to be minimal and editorial, ensuring users can quickly move from authentication into profile and taste onboarding.
Sources: README.md:120-125, AGENTS.md:310-315
System Architecture & Configuration
The authentication system relies on the Supabase Auth GoTrue server, configured specifically for code-based verification rather than magic links.
Supabase Auth Configuration
The supabase/config.toml defines the security parameters and rate limits for the OTP flow. Key configurations include:
- OTP Length: 6 characters.
- OTP Expiry: 3600 seconds (1 hour).
- Rate Limits: 30 sign-in/up requests per 5 minutes per IP; 30 token verifications per 5 minutes per IP.
- Confirmations:
enable_confirmations = trueis required to ensure email validity.
Sources: supabase/config.toml:210-250, README.md:126-128
Email Delivery System
Kocteau uses a "code-only" email strategy. Both the "Magic Link or OTP" and "Confirm Signup" templates in Supabase must use the {{ .Token }} variable. The application explicitly avoids including {{ .ConfirmationURL }} to prevent confusing loops, as verification is handled directly within the Kocteau web client.
Sources: apps/web/emails/README.md:15-25, README.md:129-132
Authentication Lifecycle
The authentication process follows a strict sequence from email submission to session establishment and subsequent onboarding redirects.
This diagram illustrates the end-to-end flow from initial request to authenticated redirect.
Sources: apps/web/components/auth/otp-auth-page-client.tsx:210-265, README.md:144-150
Step 1: Requesting the Code
The OtpAuthPageClient component manages the "email" step. It validates the email against the authEmailSchema before calling supabase.auth.signInWithOtp. This function is configured with shouldCreateUser: true, allowing new users to sign up seamlessly through the login form.
Sources: apps/web/components/auth/otp-auth-page-client.tsx:190-215
Step 2: Verification
Once the code is sent, the UI transitions to the "code" step. The client verifies the token using the verifyKocteauEmailOtp utility.
| Function | Purpose | Location |
|---|---|---|
sendOtp | Initiates the Supabase OTP request and handles cooldown timers. | otp-auth-page-client.tsx:190 |
verifyCode | Validates the 6-digit input and attempts to establish a session. | otp-auth-page-client.tsx:243 |
redirectAfterAuth | Logic for routing users after successful authentication. | otp-auth-page-client.tsx:166 |
Sources: apps/web/components/auth/otp-auth-page-client.tsx:166-260
Post-Authentication Routing
Kocteau uses a state-dependent redirection logic to ensure users complete their profile setup before accessing the main feed.
Onboarding State Logic
After verification, the system checks the profiles table to determine the user's progress:
- New Users: If
onboardedis false/null, redirect to/onboarding. - Incomplete Taste: If
taste_onboardedis false, redirect to/onboarding/taste. - Complete: Redirect to the requested
nextpath or the home feed (/).
Logic flow for determining the user's destination post-login.
Sources: apps/web/components/auth/otp-auth-page-client.tsx:140-165, apps/web/app/(auth)/onboarding/page.tsx:40-60
Security & Rate Limiting
The system implements several layers of protection to prevent abuse:
- Cooldown Timers: A 60-second client-side cooldown is enforced before a user can request a fresh code.
- Input Validation:
zodschemas (authEmailSchema,otpCodeSchema) ensure only valid data reaches the Supabase API. - Database Level:
rate_limit_windowstable in Postgres handles server-side rate limiting without requiring Redis.
Sources: apps/web/components/auth/otp-auth-page-client.tsx:24-30, README.md:135-138, supabase/config.toml:235-245
Conclusion
The Authentication and OTP flow in Kocteau is a centralized gateway designed for low-friction entry. By leveraging Supabase Auth's code-based verification and a custom client-side state machine, the project ensures a secure, passwordless experience that transitions directly into a personalized music discovery environment.