SuperTokens Passwordless Node.js Demo

What it is

This project is a reference implementation of passwordless authentication. It replaces traditional passwords with time-limited, single-use magic links sent to the user's email. The system consists of a static HTML frontend for inputting emails and verifying tokens, an Express.js backend handling session management and SuperTokens integration, and a SuperTokens Core instance running in Docker with PostgreSQL for persistent storage.

Features

• Passwordless login via email magic links
• Single-use, time-limited authentication tokens (15 min expiry)
• Session management with HTTP-only cookies
• Dockerized SuperTokens Core and PostgreSQL setup
• Express.js backend with CORS configuration
• Static frontend with login and dashboard views

Quickstart

docker-compose up -d
npm start
npx serve -s .

Architecture

flowchart TD
    User[User Browser] -->|HTTP Request| Frontend[Static Frontend :3000]
    Frontend -->|API Call| Backend[Node.js/Express Server :3001]
    Backend -->|Auth Logic| ST_SDK[supertokens-node SDK]
    ST_SDK -->|HTTP API| Core[SuperTokens Core :3567]
    Core -->|Read/Write| DB[(PostgreSQL :5432)]
    Backend -->|Log Link| Console[Server Console]

How it's built

The backend uses the `supertokens-node` SDK with Express middleware to handle auth routes. The SuperTokens Core (v9.3.0) runs in a Docker container alongside PostgreSQL. The frontend is a static site served via `npx serve`, interacting with the backend API. Magic links are logged to the server console instead of being sent via SMTP for demonstration purposes.

How it runs

sequenceDiagram
    participant U as User
    participant F as Frontend (:3000)
    participant B as Backend (:3001)
    participant S as SuperTokens Core
    participant D as PostgreSQL

    U->>F: Enter Email & Click Send
    F->>B: POST /auth/signinup/code
    B->>S: Create Code (Email)
    S->>D: Store Code & Hash
    S-->>B: Return PreAuthSessionID
    B-->>F: Success Response
    B->>B: Log Magic Link to Console

    U->>U: Copy Link from Console
    U->>F: Open Magic Link
    F->>B: GET /auth/signinup/code/consume
    B->>S: Consume Code
    S->>D: Validate & Delete Code
    S-->>B: Return Session Tokens
    B-->>F: Set Session Cookie & Redirect
    F->>U: Show Dashboard

How to apply & reuse

Use this as a starting point for integrating passwordless login into Node.js applications. Replace the console-based email delivery with a real SMTP provider (e.g., SendGrid, AWS SES) by modifying the `emailDelivery` override in `server.js`. Customize `appInfo.js` with your production domains.

At a glance