Library · Security architecture

Authentication architecture.

By Mokshify Engineering · Reviewed by the team · Updated 17 Jul 2026 · 6 min read

The problem

Authentication is the front door of every product and the first thing attackers try. It must be secure enough to survive hostile attention, smooth enough that real users get in without friction, and boring enough that your team never has to think about it at 2am. Most teams get at most two of the three.

The architecture

The shape we ship: an identity service speaking OpenID Connect issues a short-lived access token (verified by every service on every call) and a rotating, revocable refresh token. Authorization is separate from authentication - every privileged action is checked at the point of execution and written to an audit log, because knowing who someone is says nothing about what they may do.

Advantages & disadvantages

Advantages: stolen access tokens expire in minutes; refresh rotation turns token theft into a detectable event; per-service verification means no service trusts the network; SSO and MFA bolt onto the identity service without touching products. Disadvantages: more moving parts than a session cookie on one server; token lifetime tuning is a real product decision (too short annoys users, too long comforts attackers); clock skew and revocation lists are operational details that must actually be operated.

Tradeoffs & the honest shortcut

For a single-server MVP, a well-configured session cookie (HttpOnly, Secure, SameSite) is simpler and safer than a badly built token system - the token architecture earns its complexity when multiple services and client surfaces arrive. We often start MVPs on sessions and migrate on schedule, an escape hatch planned like tenancy promotion.

Technology selection

Managed identity providers where they fit (fewer credentials to defend), FastAPI/Node middleware for verification (ADR-002), PostgreSQL for the authorization model and audit trail (ADR-003), Redis for rate-limiting login attempts (ADR-004). Never build password hashing yourself; never store what a vault should hold.