The link that locked out the new hire

Oct 28, 2026AI Reliability Engineering5 min read

The bug shipped, and the way you would have found it is this.

Good engineering is mostly a list of things that were not allowed to show.

A new employee gets an email on their first morning with a single link in it. They open it on their phone. The page loads. They put the phone down to find their headphones, the screen locks, and when they come back they pull to refresh.

The link is dead. It is their first day, and the first thing the company gave them does not work.

We built that system at Aditi for a staffing client, and I want to walk through what happens when that link is clicked, because the sequence is genuinely interesting, and because the bug sits exactly where a reasonable person would put it.

The design, and the reason for it

The joining call has three participants: the new employee, an AI that runs the structured part of the call, and a member of the HR team who watches and steps in.

The new employee should not have to do anything to get there. No account, no password, no app. A person who has not started yet does not exist in your identity system, and making their first interaction with the company a password reset is an odd way to say welcome.

So: one link, one use, no login. Which puts every hard problem in the token.

What the token has to survive

A single-use link in an email is a small object with a lot of hostile conditions around it.

It gets forwarded. It sits in an inbox that syncs to three devices. Corporate mail scanners fetch every URL in every message to check it for malware, which means the link may well be requested by a machine in a datacentre before the human ever sees it. The recipient opens it, closes it, reopens it. Their phone reloads the tab from cold after a while. They refresh when the page seems slow.

Every one of those is a legitimate reason to request that URL more than once.

Here is the fix that went in:

fix: stop marking joiner link used on page load so candidate can open it

The original implementation marked the link consumed when the page loaded, which is the obvious place to put it and is wrong for every reason in the list above. Single-use has to mean single claim, not single fetch. Loading the page is not the event that matters. Claiming the session is.

So the flow separates them. The page load validates the token and renders. A distinct claim command runs when the joiner actually enters the call, and that is what burns the link. Refreshing before you join costs nothing. The mail scanner fetching your URL costs nothing.

I have written variations of this bug before and I expect I will again, because the correct behaviour is only obvious once you have listed the ways a URL gets requested by things that are not the user. That list is longer every year.

Validated, not trusted

The second thing that happens is that the token is checked rather than believed.

The link carries a signed token. The server validates the signature, checks expiry, and looks the link up in the database to confirm it exists, belongs to the candidate it claims to, and has not already been claimed. Only then is a session token issued for the actual call.

Both halves are necessary and people routinely skip the second. A valid signature proves the token was issued by us and has not been altered. It proves nothing about whether it is still meant to work. Revocation, expiry in the sense of “this call already happened”, and the claim state all live in the database, because they are facts about the world rather than facts about the string.

The cost of that database round trip is a few milliseconds on a flow that takes the better part of a minute. It buys the ability to invalidate a link, which you will need the first time HR sends one to the wrong address.

Then the call has to assemble

Once the session is real, three third-party services have to start in the right order before the new employee hears anything: the media channel first because its failure is unrecoverable, then the voice agent because it needs the employee’s profile to say their name, then the avatar last because it is the most expensive and the least essential. Nothing shows on screen until all of it is ready, because a face that appears before the voice reads as broken in a way that a few more seconds of a loading state does not. I will write about that assembly order, and why it follows cost of failure rather than dependency, in a separate post on the same system, so I will not repeat it here.

The one we backed out

Getting participants to see each other took three attempts, and the middle one is in the history as a revert:

fix: iterate remoteParticipants at join time so HR and joiner see each other's video
fix: move remoteParticipants iteration into stateChanged→Connected handler
Revert "fix: move remoteParticipants iteration into stateChanged→Connected handler"

The problem: when you join a call, the other people already in it need to be enumerated so their video can be rendered. Do it at join time and you race, because the participant list may not be populated yet. So the second attempt moved it into the connection state handler, which is the textbook answer and reads better.

It was reverted, because the state event does not fire in every path into a connected call. Rejoining after a network blip, in particular, can put you in a connected call without the transition you were waiting for. The version that survived handles both: enumerate at join, and again on the state change, idempotently.

That is not elegant. The elegant version is the one we backed out. I have made a reasonable peace with this: in real-time media, the state machine described in the documentation and the state machine you observe are related but not identical, and the code has to be written against the second one.

The same lesson showed up in a smaller way with the mute button, which for a while muted the interface without muting the media, so HR could still hear a new employee who believed they were muted. On a call where somebody is being asked about their previous employment, that is not a cosmetic defect.

What travels

Strip out the avatars and the onboarding and what is left is a pattern that applies to any passwordless flow into a live session.

Separate the fetch from the claim. A URL is requested by more things than your user. Consume the token at the moment of intent, never at the moment of retrieval.

Validate against state, not just signature. The signature says we issued it. The database says whether it should still work. You need both, and only one of them is free.

Order the assembly by cost of failure, not by dependency alone. The component that cannot be recovered from goes first. The expensive optional one goes last, so it can be dropped.

Write against the state machine you observe. Not the one in the sequence diagram. Ours came out of a revert, which is the honest way to learn it.

The whole sequence takes under a minute, and the entire measure of whether it worked is that the person on the other end never thought about any of it. Good engineering is mostly a list of things that were not allowed to show.