Login Flow

COMING SOON

This page is under construction. Check back soon for complete documentation.

Complete guide to implementing user login in your application.

Overview

This guide will cover:

• Login form implementation
• Email/username authentication
• Password validation
• Session handling
• Error handling
• Two-Factor Authentication (2FA) flow

---

Two-Factor Authentication (Conditional Flow)

When the Two-Factor Authentication module is active, the login flow behaves differently for users who have 2FA enabled. Complete reference available in the Two-Factor API.

The Partial Session

If a user successfully authenticates with an email/password (or OAuth) but requires 2FA, the server will not return an immediately valid session. Instead, you'll receive a partial session:

{
  "requires_2fa": true,
  "session_id": "ses_xxxxxxxxxxx",
  "available_methods": ["email"]
}

The emitted session_id has a specific pending status and a short expiry limit (default 5 minutes). This partial session can only be used to access 2FA resolution routes.

Resolving 2FA (Client-Side)

1. Store the session_id temporarily in your client as you normally would.
2. Prompt the user to enter the 6-digit code sent to their email or sms.
3. Submit the code back to the /auth/two_factor/verify endpoint, including the session_id cookie or header:

curl -X POST https://your-instance.pubflow.com/auth/two_factor/verify \
  -H "Content-Type: application/json" \
  -H "Cookie: session_id=ses_xxxxxxxxxxx" \
  -d '{
    "code": "123456",
    "method": "email",
    "action": "login"
  }'

Full Session Activation

Once the code is verified successfully, the backend automatically promotes the session:

• The session status changes from pending to active.
• two_factor_verified becomes 1.
• The full expiry (e.g., 30 days) is applied.
• A new, fully valid session_id cookie is returned in the response.

From this point, the session is indistinguishable from a standard login session and can be verified by your Flowfull backend utilizing the Bridge Validation Architecture.

---

Coming Soon

Full implementation guide with:

• React login component
• Backend validation
• Session management
• Error handling
• Best practices

---

Next Steps

• User Registration - Registration guide
• Password Reset - Password reset flow
• Authentication API - API reference