Magic Links

• 19 January 2026
• System Design,
• Magic Links,
• Go,
• TL2

Hey, I hear you! In the previous post, I gave an example System Design writeup for XYZ Auth to implement Magic Links for the organisation. However, remember that System Design documents are living documents, and the previous post was just to highlight the structure of the document.

In this post we will build upon the System Design in the previous post with details on how Magic Links will be implemented. Specifically, we will create technical artifacts to be placed in the Tactical Design section of the System Design document.

Sequence Diagrams

The best way to explain how Magic Links work is to use Sequence Diagrams.

The above sequence diagram shows the happy path of a Magic Link usage.

1. Users enter their email in the Login page.
2. The backend checks if the email exists in the database.
3. If the email exists, generate an encrypted cookie detailing who the user is.
4. Create a Magic Link with the encrypted cookie as a URL param.
5. Send the Magic Link to the user's email address.
6. User clicks the Magic Link, and upon success, gets redirected to the protected page.

One of the beautiful features of Magic Links is that they use Stateless Cookies. Stateless means that the backend does not need to verify if the content in the Cookie is valid or not; it simply trusts it. This greatly reduces the number of network calls to databases as shown in the sequence diagram above; there is only 1 database call at the beginning, and future visits to protected resources will simply succeed if the Cookie has not expired.

In order to prevent manipulation of the Cookie, the Cookie will be encrypted by the server during creation. Only the server has the private key, hence adversaries will not be able to mutate the Cookie to suit their needs. Referring to the System Architecture diagram in the previous post, these private encryption keys will be stored in Vercel's Key-Value stores, such that the backend will have access to them to decrypt / validate incoming requests and their respective Cookies.

Non-Functional Requirements

There are security pitfalls associated with Stateless Cookies, and these need to be captured in the Non-Functional Requirements of a System Design document.

Example Additional requirements:

• The encryption key needs to be rotated every 7 days.
• The Cookie in the Magic Link should expire within 15 minutes.
• Refreshed Cookies should expire within 60 minutes, before needing a new Magic Link.
• To adopt the Double-Submit Cookie Pattern, when generating a Cookie.

• ← Previous
  System Design
• Next →
  CSRF with Magic Links