Flow
One request, start to finish
1Token checked
Signature is real; only user, company and session are read.
2Live records loaded
Session, user, workspace, settings and current roles.
3Dead sessions stopped
Revoked, expired, shut off or no role left means no.
4Second factor worked out
Turned on, required by the workspace, or a sensitive permission.
5Access read twice
Catches a role change that lands mid-request.
6Answer or a clear no
401 means sign in again; 503 means try again soon.
Who anyone was remained a mystery to the new API. On every request it asked the old API who the caller was and what they could do, and it believed the answer. That got me through the first part of moving my scheduling and payroll app to a new API, but it meant an extra network call each time and a tie to the old service. This week I cut that tie. The new API now checks sessions on its own.
Only three fields count
My login token holds a handful of fields, among them user, organization, session, role, a second-factor bit and a PIN-change flag. The new code checks the signature, then reads just user, organization and session. It ignores the rest.
Everything that decides access is loaded from the database on that request: the session, the user, the workspace, its settings and the user's current roles. If the session is revoked or expired, the user or workspace is shut off, or no role is left, the answer is no. A demotion takes effect on the next request.
A session ends at whichever comes first: its own expiry or the workspace's timeout. A broken timeout setting falls back to a default, so it can't stretch a session past that default.
The second factor gets derived
A second factor is needed if the user turned it on, if the workspace requires it, or if they hold a sensitive permission like payroll or user admin. Both APIs share one list of those permissions. Whether the user passed the check is kept in Redis.
Roles can change mid-request, so the code reads the user's access, checks Redis, reads access again, and checks Redis again only if the second-factor rule just switched on.
Two different ways to say no
A bad or dead session gets a 401, meaning sign in again. A database or Redis that won't answer gets a 503, meaning try again soon. Unknown errors count as 503, never as a pass. The mapping is deliberately coarse.
Sign-in failures get a 401, and everything else gets a 503.
If Redis is down when the server starts, it won't start.
Garbage headers, forced PIN changes and cookie lifetimes
A broken Authorization header is refused. It doesn't fall back to the cookie. Scheduling now refuses to run until a pending second factor or forced PIN change is done. Re-issued cookies can't outlive the session. Role names are cleaned before display.
What the old API reads, and when the marker goes
The old API still handles most other requests, so I need to check what it reads off the re-issued cookie. I also don't know yet whether the Redis marker is wiped when a session ends.