Skip to main content

Request Flows

Admin Signup​

sequenceDiagram
    autonumber
    Browser->>+API: POST /api/admin/signup {email, password, name}
    API->>+DB: INSERT INTO admin_users
    API->>+DB: INSERT INTO admin_sessions
    API-->>-Browser: 201 {admin, session cookie}
    Note over Browser: Sets HttpOnly session cookie

Admin Login & Session Restore​

sequenceDiagram
    autonumber
    Browser->>+API: POST /api/admin/login {email, password}
    API->>+DB: SELECT FROM admin_users WHERE normalized_email
    API->>+API: scrypt verifyPassword()
    API->>+DB: INSERT INTO admin_sessions
    API-->>-Browser: 200 {admin, session cookie + CSRF cookie}
    
    Note over Browser: Page reload / new tab
    Browser->>+API: GET /api/admin/me (cookie sent automatically)
    API->>+DB: SELECT FROM admin_sessions WHERE token_hash
    API-->>-Browser: 200 {admin} or 401

Project User Signup​

sequenceDiagram
    autonumber
    App->>+API: POST /api/projects/{id}/auth/signup {email, password} + x-kyqu-public-key
    API->>+DB: SELECT FROM project_api_keys WHERE public_key
    alt Invalid key
        API-->>-App: 401
    end
    API->>+DB: INSERT INTO project_users
    alt Email verification required
        API->>+DB: INSERT INTO project_auth_tokens (verification)
        API->>+API: Send email via SMTP/outbox
        API-->>-App: 201 {user, session: null, verificationRequired: true}
    else Verification not required
        API->>+DB: INSERT INTO project_sessions
        API-->>-App: 201 {user, session: {token, expiresAt}}
    end

Project User Login​

sequenceDiagram
    autonumber
    App->>+API: POST /api/projects/{id}/auth/login {email, password} + x-kyqu-public-key
    API->>+DB: Validate public key
    API->>+DB: SELECT FROM project_users WHERE normalized_email
    API->>+API: scrypt verifyPassword()
    
    alt Account locked
        API-->>-App: 401 {unlockAt}
    end
    
    alt TOTP required
        API-->>-App: 403 TOTP_REQUIRED
        App->>+API: POST login {totpCode: "123456"}
    end
    
    API->>+DB: INSERT INTO project_sessions
    API-->>-App: 200 {user, session: {token, expiresAt}}

Email Verification Flow​

sequenceDiagram
    autonumber
    App->>+API: POST /api/projects/{id}/auth/verify-email/request {email}
    API->>+DB: CREATE one-time verification token
    API->>+DB: INSERT INTO project_email_outbox
    API-->>-App: 200 {ok: true}
    
    Note over User: Clicks link in email
    User->>+API: GET /api/projects/{id}/auth/verify-email/confirm?token=...
    alt Has email_verified_url
        API-->>-User: 302 → email_verified_url?verified=1
    else No redirect URL
        API-->>-User: 200 {user}
    end
sequenceDiagram
    autonumber
    App->>+API: POST /api/projects/{id}/auth/magic-link/request {email}
    API->>+DB: CREATE one-time magic link token
    API-->>-App: 200 {ok: true}
    
    Note over User: Clicks link in email
    User->>+API: GET /api/projects/{id}/auth/magic-link/confirm?token=...
    alt Has login_url
        API-->>-User: 302 → login_url?token={sessionToken}
    else No redirect URL
        API-->>-User: 200 {user, session}
    end

Password Reset Flow​

sequenceDiagram
    autonumber
    App->>+API: POST /api/projects/{id}/auth/password-reset/request {email}
    API->>+DB: CREATE one-time reset token
    API-->>-App: 200 {ok: true}
    
    Note over User: Clicks link in email
    User->>+API: GET /api/projects/{id}/auth/password-reset/confirm?token=...
    alt Has password_reset_url
        API-->>-User: 302 → password_reset_url?token={token}
    else No redirect URL
        API-->>-User: 400 error
    end
    
    Note over User: Submits new password form
    App->>+API: POST confirm {token, password}
    API->>+DB: UPDATE project_users password_hash
    API-->>-App: 200 {user, session}

TOTP 2FA Enrollment​

sequenceDiagram
    autonumber
    App->>+API: POST /api/projects/{id}/auth/totp/enroll (Bearer token)
    API->>+DB: Validate session, verify TOTP enabled
    API-->>-App: 200 {enrollmentUrl: "otpauth://totp/..."}
    
    Note over User: Scans QR code in authenticator app
    
    App->>+API: POST /api/projects/{id}/auth/totp/confirm {code: "123456"}
    API->>+API: verifyTotpCode(secret, code)
    API->>+DB: UPDATE project_users SET totp_enabled_at
    API-->>-App: 200 {backupCodes: [...8 codes]}