Email + password

Some apps need a password flow: shared devices, no email access, or regulatory requirements. Pylon ships built-in email + password auth. Passwords are hashed with Argon2id (the OWASP-recommended algorithm). Failed logins run a dummy hash so timing does not leak whether the email exists.

Register

curl -X POST https://your-app/api/auth/password/register \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "password": "correct-horse-battery-staple",
    "displayName": "Alice"
  }'

Response (201):

{
  "token": "pylon_a1b2c3...",
  "user_id": "usr_xyz",
  "expires_at": 1735689600
}

The user is created and signed in, with no separate “verify your email” step. If you need email verification, call /api/auth/email/send-verification after sign-in. The user can keep using the app while their email is unverified. Gate sensitive flows on User.emailVerified.

Validation rules

Rule	Enforcement
Email contains `@`	400 `INVALID_EMAIL`
Email is lowercased + trimmed	Server-side normalization
Password ≥ 8 characters	400 `WEAK_PASSWORD`
Email not already registered	409 `EMAIL_TAKEN`

displayName defaults to the email if omitted.

Log in

curl -X POST https://your-app/api/auth/password/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "password": "correct-horse-battery-staple"}'

Response (200):

{
  "token": "pylon_a1b2c3...",
  "user_id": "usr_xyz",
  "expires_at": 1735689600
}

Wrong credentials always return the same shape:

{ "error": { "code": "INVALID_CREDENTIALS", "message": "Email or password is incorrect" } }

The error message intentionally does not say which one is wrong. The server runs the password hash check even when the email does not exist, so timing analysis cannot enumerate accounts.

From the SDKs

import { configureClient } from "@pylonsync/react";

configureClient({ baseUrl: "https://your-app" });

// Register
const reg = await fetch("/api/auth/password/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password, displayName: name }),
}).then(r => r.json());

// Login
const login = await fetch("/api/auth/password/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password }),
}).then(r => r.json());

import PylonClient

let client = PylonClient(baseURL: URL(string: "https://your-app")!)
let session = try await client.signInWithPassword(
    email: "[email protected]",
    password: "correct-horse-battery-staple"
)
// token is persisted automatically

Password hashing

Pylon uses argon2 with the Argon2id variant, the winner of the Password Hashing Competition and the OWASP recommendation. It resists both side-channel attacks (Argon2i) and GPU-based brute-force (Argon2d) by design. Default parameters:

Parameter	Value	Why
Memory cost	19 MiB	OWASP minimum for interactive logins
Time cost	2 iterations	Balances login latency vs attacker cost
Parallelism	1	Server-side default
Salt	16 bytes	CSPRNG-generated per password

Each hash is self-describing. The algorithm parameters are stored in the hash string, so future Pylon versions can rotate them without breaking existing passwords.

Password reset

Pylon ships a built-in “forgot password” flow. Two endpoints email a single-use reset link and change the password after the user clicks it: 1. Request a reset link. The user submits their email:

curl -X POST https://your-app/api/auth/password/reset/request \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]"}'

Always returns 200 { "sent": true }, whether or not the email is registered. The endpoint is rate-limited and equalizes response timing across the registered and not-registered paths, so it cannot be used to enumerate accounts. When the email exists, Pylon emails a link of the form <public-url>/reset-password?token=<token>. 2. Complete the reset. Your /reset-password page reads the token from the URL and POSTs it with the new password:

curl -X POST https://your-app/api/auth/password/reset/complete \
  -H 'Content-Type: application/json' \
  -d '{"token": "<token>", "newPassword": "a-new-strong-password"}'

The token is single-use. The new password is length- and HIBP-checked (same as register). On success Pylon updates passwordHash, revokes every existing session for that user, and mints a fresh one:

{ "reset": true, "revoked_sessions": 3, "token": "pylon_...", "user_id": "usr_xyz", "expires_at": 1735689600 }

Code	Status	Meaning
`MISSING_EMAIL`	400	No `email` on request
`MISSING_FIELD`	400	`token` or `newPassword` missing on complete
`WEAK_PASSWORD`	400	New password shorter than 8 chars
`PWNED_PASSWORD`	400	New password found in the HIBP breach corpus
`INVALID_TOKEN`	401	Reset token is wrong, expired, or already used
`RATE_LIMITED`	429	Too many reset requests

If you do not want a password-reset UI, run users through the magic-code flow instead. It mints a session without a password. Then update User.passwordHash yourself from an authenticated action.

Configuring the User entity

Password auth expects a User entity with these fields (auto-created by pylon init):

{
  "name": "User",
  "fields": [
    { "name": "email",        "type": "string",  "unique": true,  "optional": false },
    { "name": "displayName",  "type": "string",  "optional": false },
    { "name": "passwordHash", "type": "string",  "optional": true },
    { "name": "avatarColor",  "type": "string",  "optional": true },
    { "name": "emailVerified","type": "datetime","optional": true },
    { "name": "createdAt",    "type": "datetime","optional": false }
  ]
}

passwordHash is optional because users who signed up via OAuth or magic code never had one. emailVerified is null until they prove control of the email.

Security notes

Never deserialize AuthContext from request body. The Rust side intentionally doesn’t derive Deserialize so a client can’t forge is_admin: true. Identity comes from the session lookup, not the wire.
/api/auth/session POST is gated — only dev mode or admin token can mint a session for an arbitrary user_id. Your registration/login endpoints are the only public ways to obtain a token.
Sessions expire after 30 days by default — see Sessions to change.
/login is rate-limited by default — the built-in per-IP/per-email limiter throttles the credential bucket (login, register, reset, TOTP verify) and returns 429 RATE_LIMITED with a retry_after hint on abuse. Pylon Cloud layers additional per-IP limiting at the edge.

When to use password vs alternatives

Use password when:

Email isn’t reliable (offline-first apps, regions with poor SMTP delivery)
Compliance requires it
Users explicitly prefer it

Otherwise prefer magic codes (no memory load, email is verified by construction) or OAuth (zero credentials your service stores).

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Email + password

Register

Validation rules

Log in

From the SDKs

Password hashing

Password reset

Configuring the User entity

Security notes

When to use password vs alternatives

​Register

​Validation rules

​Log in

​From the SDKs

​Password hashing

​Password reset

​Configuring the User entity

​Security notes

​When to use password vs alternatives

Register

Validation rules

Log in

From the SDKs

Password hashing

Password reset

Configuring the User entity

Security notes

When to use password vs alternatives