How token security works — in plain terms

A web app has a problem: after you log in, how does it remember it's you on every click — without asking for your password again, and without letting a thief pretend to be you?

🏨 Think of a hotel. You prove who you are once at the front desk, and you get a keycard. The keycard opens your room for the rest of your stay — but it's designed so that if someone copies it, the hotel notices. That's exactly how token security works.

🎭 The cast

Four characters. Each has a plain name and a real technical name.

🛎️

The front desk

Checks your ID once and hands out keycards. Also the only one who can look up who you are.

The API / auth server

🪪

Your ID

You show it once at check-in — your email + Microsoft/Google login or a magic link. Never shown again.

💳

The keycard

Opens doors for a short time (15 min). You carry it in your pocket. If lost, it expires fast.

Access token (JWT), in memory

🎟️

The renewal ticket

Kept in the hotel safe — you can't take it out or even see it. It's used behind the scenes to print you a fresh keycard.

Refresh token (HttpOnly cookie)

🗺️ The whole flow, step by step

🪪

Check in (log in)

You show your ID once. The front desk verifies it and prepares your stay.

Magic link or Microsoft/Google → the API confirms your identity.

💳🎟️

Get a keycard + a renewal ticket

You pocket the keycard (works 15 min). The renewal ticket goes straight into the hotel safe — you never touch it.

JWT returned to the app (memory); refresh token set as an HttpOnly cookie the browser stores but JS can't read.

🚪

Open doors

Every door you open, you tap the keycard. Fast, no password.

Each API call sends Authorization: Bearer <JWT>.

🔄

Silent renewal (before it expires)

Just before your keycard stops working, the system quietly walks to the safe, uses the renewal ticket, and prints you a fresh keycard — you don't notice a thing.

The app calls /auth/refresh; the old refresh token is swapped for a new one (rotation).

🕵️

Each ticket is single-use — copies get caught

Every renewal ticket works once. If two people ever show up with the same ticket, the front desk knows one is a thief and cancels the whole room immediately.

Refresh rotation + reuse detection: reusing a rotated token revokes the entire session chain.

⏰

“Still there?” (idle timeout)

If you don't move for 30 minutes, a little notice pops up: “Still around? Staying?” — click Stay and you're good; ignore it and you're signed out.

Idle timer → the SessionWarningDialog with a 2-minute countdown.

🚪🔒

Checkout time (absolute cap)

No matter how many renewals, there's a hard checkout — after the max stay you check in again. Keeps a forgotten session from living forever.

Absolute session cap (e.g. 8h). No refresh succeeds past it.

🌙

Close the app and come back later

The renewal ticket stays in the safe even after you close everything. Come back soon and you're waved right back in. Come back much later (say, the next morning) and you check in again — on purpose, because this app handles money.

Refresh cookie is persistent, but the 30-min sliding window decides: reopen within it → auto signed-in; past it → re-login. An optional “Remember me” can widen that window on trusted devices.

🛡️ Why this is safe

🔒 The ticket stays in the safe

The renewal ticket (refresh token) is locked in the browser where scripts can't reach it. Even a malicious script on the page can't steal it.

⏱️ The keycard dies fast

A lost keycard (JWT) only works 15 minutes — and it can't be turned into a lasting copy without the safe's ticket.

🕵️ Copies trip the alarm

Single-use renewal + reuse detection means a copied session gets the whole chain revoked the moment it's replayed.

📡 Nothing travels in the clear

Everything is over HTTPS, and the ticket refuses to be sent along on requests coming from other websites.

📇 Cheat sheet

	Plain name	Real term	What it does
🛎️	Front desk	API / auth server	Verifies identity, issues tokens
🪪	Showing your ID	Login (OAuth / magic link)	Prove who you are — once
💳	Keycard	Access token (`JWT`)	Opens doors for 15 min; kept in memory
🎟️	Renewal ticket in the safe	Refresh token (`HttpOnly` cookie)	Prints fresh keycards; JS can't read it
🔄	Quiet keycard swap	Refresh rotation	New token every renewal
🕵️	Same-ticket alarm	Reuse detection	Revokes the whole session if copied
🎫	Anti-forgery stamp	CSRF nonce (`SameSite`)	Blocks other websites from acting as you
⏰	“Still there?”	Idle timeout + warning	Signs out after inactivity
🚪🔒	Checkout time	Absolute cap	Hard limit on how long a stay can last