Add Turalogin email authentication to my app. Here's how it works:
1. My backend calls Turalogin API to start auth (sends email to user)
2. User receives email with BOTH a clickable magic link AND a 6-digit code
3. User chooses: Click link (instant) OR enter code manually (if link doesn't work)
4. My backend verifies the token/code with Turalogin API (server-side only)
5. On success, I create my own session/cookie - Turalogin never touches my frontend
API Details:
- Base URL: https://api.turalogin.com/api/v1
- IMPORTANT: Every API request MUST include the Authorization header:
Authorization: Bearer <TURALOGIN_API_KEY>
Security Notes:
- The /auth/verify endpoint MUST be called server-side only (never from browser)
- Your TURALOGIN_API_KEY must never be exposed to the client
Endpoints:
POST /auth/start
Body: {
email: string,
method?: 'magic_link' | 'otp', // Optional, defaults to 'magic_link'
validationUrl?: string // Required for magic_link method
}
Returns: { sessionId, method, message, expiresAt }
- method='magic_link': Email contains clickable link + 6-digit code
- Link format: {validationUrl}?token={sessionId}
- User can click link OR enter the 6-digit code
- method='otp': Email contains ONLY 6-digit code (no link)
- For pure OTP flow without links
POST /auth/verify
Body: {
sessionId: string, // From URL token parameter or from /auth/start response
code?: string // Optional 6-digit code for verification
}
Returns: { success, token, user: { id, email }, expiresIn }
- IMPORTANT: Pass the "token" from URL query params as "sessionId" in the request body
- If user enters the 6-digit code, pass it in the "code" field
- expiresIn is in seconds (86400 = 24 hours)
Error Responses:
- 400: Missing or invalid parameters
- 401: Invalid, expired, already-used session, or wrong verification code
- 500: Server error (retry with exponential backoff)
Session Constraints:
- Magic links and OTP codes expire after 15 minutes
- Each link/code can only be used once (single-use)
- After verification, create your own session - Turalogin does not manage sessions
Authentication Methods:
- **magic_link** (default): Email contains clickable link + 6-digit code. User chooses which to use.
- **otp**: Email contains ONLY 6-digit code (no link). Pure OTP flow.
Environment Variables:
- TURALOGIN_API_KEY: Your API key from the dashboard
- TURALOGIN_REDIRECT_URL: The URL where magic links redirect to (required for magic_link method)
- Development: http://localhost:3000/auth/magic-link
- Production: https://myapp.com/auth/magic-link
Example fetch call:
fetch('https://api.turalogin.com/api/v1/auth/start', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.TURALOGIN_API_KEY}`
},
body: JSON.stringify({
email,
method: 'magic_link', // 'magic_link' or 'otp'
validationUrl: process.env.TURALOGIN_REDIRECT_URL // required for magic_link
})
})
Please create:
1. Auth endpoint to start authentication (calls Turalogin /auth/start with email, method, and validationUrl)
2. Auth verification page/endpoint that:
- Extracts token from URL (for magic link clicks)
- OR accepts 6-digit code input from user
- Calls Turalogin /auth/verify server-side with sessionId and optional code
3. Login page/form with email input
4. After email submission, show a confirmation page telling the user:
- "Check your email for a login link from Turalogin.com"
- "You can also enter the 6-digit code from the email"
- Optionally include a code input field on the same page
5. Use proper error handling for all error cases (400, 401, 500) and loading states
6. Set up environment variables for both TURALOGIN_API_KEY and TURALOGIN_REDIRECT_URL