Every Flutter starter kit solves the login screen. Almost none of them solve what comes after it.
I spent the last few weeks building the "after" part for a real SaaS app, and it turned out to be six distinct problems — each one with a gotcha I didn't see coming. Here's what I learned, with the details that cost me the most time.
Token refresh is a queueing problem, not a retry problem
The naive version: catch a 401, call /auth/refresh, retry the request. This works right up until your app fires three requests at once on a cold start. All three get a 401, all three call refresh, and now you have a race — two of them refresh with a token that's already been rotated server-side, and your user gets logged out for no reason.
The fix is to treat refresh as a single-flight operation. When a 401 arrives, check whether a refresh is already in progress. If it is, queue the request and wait for the result instead of starting a second refresh:
