API

Email/password Auth

20 steps 21 files 5 packages No dependencies

This pack adds email and password authentication to your API as JSON endpoints. It fits the guard your app already authenticates with, access tokens or session, enhancing your existing login and signup rather than replacing them. Every new account confirms its email address before it is treated as active.

Email verification for new signups, with a resend endpoint and a 403 on unverified access.
Rate-limited login and signup that penalise repeated failed attempts.
A branded, MJML-based confirmation email that links to your frontend.

Apply the authentication pack with Flow. Start a new session in your selected coding agent and execute the following slash command inside it.

$ claude

> /flow.apply auth

After applying, Flow will make the following changes to your app:

Discover your default guard, access tokens or session, and enhance the login and signup controllers you already have.
Land the backend as shipped, from the migrations and model mixin through the validators, the email-verifications controller, routes, middleware, and mailer.
Configure mail and the limiter, install Edge for the email templates, and point the verification link at your FRONTEND_URL.
Run the tests, drive the endpoints, and hand you a brief for the frontend to build against.

Apply the authentication pack to your API by hand by working through the steps below in order. Each one builds on the last, taking your API from no auth to a working signup, login, logout, and email-verification flow.

Confirm your setup
This pack fits your app's existing auth. Confirm three things before continuing.
- Your default guard. In config/auth.ts, read the default guard and its definition. A sessionGuard means you follow the Session guard blocks below, a tokensGuard means the Token guard blocks. The API starter defaults to the web session guard.
- A serialize helper and a UserTransformer. Controllers return their payloads through serialize() and UserTransformer.transform(), landing the body under a top-level data key. The API starter ships both.
- The auth named middleware. The authenticated routes gate on it.

Unlock access

Only Plus subscribers can access the documentation

Delta will differ

Flow adapts the pack to your app, so the exact set of created and edited files depends on what you already have, including which guard you authenticate with. This is the shape of an apply onto the API starter kit.

Migrations

xxxx_add_unverified_email_to_users.ts created

xxxx_create_email_verification_tokens.ts created

Model

user.ts edited

Validators

user.ts edited

Controllers & responses

email_verifications_controller.ts created

session_controller.ts edited

new_account_controller.ts edited

user_transformer.ts edited

Middleware

verified_account_middleware.ts created

Mailers & email templates

account_activation_provision.ts created

email_layout.edge created

account_activation.edge created

Routes & config

routes.ts edited

mail.ts created

limiter.ts created

app.ts edited

env.ts edited

Factories & tests

user_factory.ts created

signup.spec.ts created

email_verification.spec.ts created

Configuration

Verification is backed by the withManagedEmail() mixin on the User model, which stores each token in a database table. Pass an options object to the mixin to change its defaults.

expiresIn

string | number

How long a verification token stays valid, as a number of seconds or a time expression. Defaults to 1 day.

table

string

The table verification tokens are read from and written to. Defaults to email_verification_tokens.

tokenSecretLength

number

The length of the random secret behind each token. Defaults to 40.

app/models/user.ts

export default class User extends compose(
  UserSchema,
  withAuthFinder(hash),
  withManagedEmail({ expiresIn: '2 hours' }) 
) {}

Verification is two email columns, not a boolean

The mixin tracks verification with two columns:

email is the confirmed address.
unverifiedEmail is one still waiting on confirmation.

Signup writes the same value to both, so the two agree and the account reads as unverified. Confirming the address moves it into email and clears unverifiedEmail, so they diverge and the account reads as active. hasInactiveAccount exposes this state, and VerifiedAccountMiddleware gates on it.

Verification tokens

Tokens live in the email_verification_tokens table, one row per outstanding token, linked to the user by tokenable_id. The mixin generates a token when you ask for one and verifies it when the link comes back, storing only its hash so a leaked row cannot be turned back into a working link.

Resend throttling

Resending is throttled to one token a minute. Inside that window the endpoint does nothing and answers exactly as it would have, so the timing stays invisible to callers.

Rate-limited credentials

one scoped per IP, and
a stricter one per IP-and-email that adds a 20-minute block after five failures, which slows a targeted guess at a single account.

Both run through penalize, which spends the budget only when credentials fail, so a valid login is always free.

app/controllers/session_controller.ts

const ipKey = `login_${request.ip()}`
const emailKey = `login_${request.ip()}_${payload.email}`

const loginLimiter = limiter.multi([
  { duration: '1 min', requests: 10, key: ipKey },
  { duration: '1 min', requests: 5, blockDuration: '20 mins', key: emailKey },
])

const [error, user] = await loginLimiter.penalize(() => {
  return User.verifyCredentials(payload.email, payload.password)
})

Signup takes a simpler guard, formsThrottle, a named limiter capped at ten requests a minute per route and IP.

start/limiter.ts

export const formsThrottle = limiter.define('forms', (ctx) => {
  return limiter
    .allowRequests(10)
    .every('1 minute')
    .usingKey(`${ctx.route?.name ?? 'global'}_${ctx.request.ip()}`)
})