User Lifecycle State Machine
A user lifecycle state machine is an explicit model of the account states a person can occupy and the allowed transitions between them, with required security side effects for each transition. It connects identity status to sessions, tokens, grants, entitlements, audit records, and data-retention behaviour.
The problem it solves is hidden account behaviour. Without a state machine, signup code, login middleware, admin panels, billing tasks, support scripts, and deletion jobs each make their own assumptions about what a user is allowed to do. That is how suspended accounts keep valid refresh tokens, deleted users remain authorised through cached grants, or unverified accounts gain access meant only for trusted users.
Concretely, the system stores a current lifecycle state for the user, such as anonymous, registered, verified, active, dormant, suspended, or deleted. Code does not freely mutate flags; it asks to perform a named transition. That transition checks whether the move is legal, writes an audit trail, and applies side effects: expire sessions, revoke tokens, remove OAuth consents, disable API keys, update roles, trigger retention workflows, or require step-up authentication.
The trade-off is ceremony and discipline. A lifecycle model adds design work, migration work, and tests around state transitions, and it can feel heavy for a small product. It also forces uncomfortable decisions: should dormancy revoke grants or only require reauthentication, should suspension block all background jobs, and what does deletion mean under retention rules? The honest answer is usually contextual, but the decision must be explicit.
Engineers meet this in authentication services, identity providers, account tables, authorisation middleware, admin actions, privacy deletion pipelines, and incident response tooling. A common misunderstanding is treating user state as a single boolean such as disabled or deleted. Access often lives outside the user row, in browsers, devices, API clients, third-party grants, caches, and service-local entitlements. The state machine exists to make those external effects part of the contract.
Common questions
- Is this just an enum on the user table?
- No. The enum is only the storage representation. The important part is the transition contract: which moves are allowed, who can trigger them, what checks happen first, and what must happen to sessions, refresh tokens, API keys, OAuth grants, cached permissions, notifications, audit records, and data-retention jobs.
- What is the difference between identity state and access state?
- Identity state describes what the system believes about the account: anonymous, registered, verified, dormant, suspended, or deleted. Access state describes what credentials and grants currently work. They are related but separate. A user can be suspended in the database while an old session or API key still works unless the transition revokes or blocks it.
- Should deletion immediately erase all user data?
- It depends on privacy rules, product promises, fraud needs, billing records, and legal retention duties. A good lifecycle transition does not hand-wave this. It disables authentication, prevents new grants, records the action, and starts the appropriate erasure, anonymisation, or retention workflow for each class of data.