What I built:

• gated every REST route under /api/v1 behind one shared bearer token, checked once at the router level so it covers simulation, hospital, and ai endpoints without repeating myself. /health stays open on purpose, load balancers need that.
• gated the websocket too. ?token= checked before the connection even gets accepted, so trigger_event, update_config, add_bottleneck, remove_bottleneck can’t touch live sim state from some random unauthenticated client anymore.
• SECRET_KEY finally does something. used to just sit there unreferenced, now it’s the actual credential, and it’s got the startup check it was missing, refuses to boot in production if it’s still the default.
• also went and built full JWT login with viewer/operator roles along the way, then looked at it and went nah, overkill for a demo hospital sim, and reverted back to the simple shared-secret version. kept the actual gate though, that’s the part that mattered.

What broke:

• first version closed unauthenticated websocket connections with code 4401, except that happens before accept(), and turns out you can’t send a close frame on a connection that was never accepted. so it actually shows up as a plain HTTP 403 on the handshake, not 4401 like the docstring said. wire behavior just didn’t match what I wrote down.
• also, local dev was quietly broken and I didn’t notice for a bit: the backend’s real default SECRET_KEY didn’t match what .env.example said it was, so a fresh clone would 401 on literally everything out of the box.

How I fixed it:

• checked the 403-vs-4401 thing wasn’t actually a bug, just how Starlette handles closing a connection pre-accept. confirmed it with a real client hitting it with no token, still blocks fine, just not with the close code I expected. left it as-is and fixed the docs instead of chasing a non-issue.
• for the env mismatch, just made .env.example, .env.local, and the actual python default all agree, then ran the whole thing end to end again, no token, wrong token, right token, until 401s and 200s landed exactly where they should.