Whatsapp Web QR Code Authentication System Design
Explaining how to build whatsapp web authentication using qr code, the architecture and the system design.
Welcome to Coderbased, a system design newsletter that literally about designing a system that become foundation of a product and feature
Before we start, kindly to subscribe, follow me on Linkedin, Twitter and share this content to your friends. Enjoy.
As an engineer who has worked extensively using laptop, I love using WhatsApp over the web. One feature that stands out to me is the authentication process. It's incredibly easy, seamless, and provides an excellent user experience.
Since WhatsApp is primarily a mobile-first application, we don’t see this type of authentication method often. However, it’s still fascinating to break down how this feature works. While it’s not overly complex, it’s certainly cool to build. So, let's dive in.
Building Whatsapp Web QR Code Authentication
Imagine we have a chat application similar to WhatsApp called Coderbased Chat, and we want to implement a web authentication feature similar to WhatsApp’s. Before we proceed, let’s understand how WhatsApp’s authentication process works.
WhatsApp, being mobile-first, doesn’t use the typical methods like entering a password or receiving an OTP to log into the web version. Instead, the process is as follows:
Authenticate on the mobile app.
Visit web.whatsapp.com, which will display a QR code.
Scan the QR code using the WhatsApp app on your phone.
Done! You’re now authenticated on the web version and can start chatting.
For a visual reference, check out the illustration below..
Similar to WhatsApp, when you visit chat.coderbased.com, it will display a similar UI, including a QR code that can be scanned using the Coderbased App for authentication.
Additionally, to make the challenge more interesting, we’ve added another requirement: when the mobile app logs out (whether the session expires or the account is banned), the website should automatically log out as well.
How would you design a system for WhatsApp Web QR Code authentication? Feel free to contribute and share your ideas by filling out the form at this link.
Now let’s go into our proposed solution
Proposed Solution
At a high level, there are several key components involved in building this feature:
Mobile App (must already be authenticated)
Website
Chat Service: This service maintains the connection (via WebSocket) to bridge the system and frontend (both the website and mobile app).
It's common in chat systems to use WebSocket for two-way, real-time communication.Auth Service: Provides authentication information and tokens.
Here are the steps and ideas to make this feature work:
The website requests a code/token/ID, but let's call it a Guest Token from the Chat Service, which is displayed as a QR code.
The authenticated mobile app scans the QR code and retrieves the Guest Token.
The Auth Token (from the mobile app) and the Guest Token are forwarded to the Auth Service.
The Auth Service generates a new token specifically for the website, called the Web Auth Token.
The Web Auth Token is sent back to the website through the Chat Service (via WebSocket).
The website reinitializes its connection to the Chat Service, now using the Web Auth Token.
To understand more, let’s break down the details:
Website (Guest State): Generating the QR Code
The website operates in two states:
Guest State: Displayed when there is no Web Auth Token stored in the browser.
Authenticated State: Displayed when there is a valid Web Auth Token stored in the browser.
By default, when a user first visits the website, it opens in Guest State, displaying the QR code for authentication.
To generate this QR code, the website connects to the Chat Service through WebSocket, identifying itself as a Guest. The Chat Service then generates the Guest Token.
Mobile App: Scanning the QR Code
Now that the QR code is displayed on the website (from the Guest Token), the mobile app can scan it.
So, what happens when the QR code is scanned?
After scanning, the mobile app retrieves the Guest Token and sends both the Auth Token (from the mobile app) and the Guest Token to the Auth Service. These tokens are used to generate a new Web Auth Token.
The Web Auth Token is then sent to the website (browser) by notifying the Chat Service. The Chat Service, which manages all WebSocket connections, is able to send the token to the correct recipient.
Website (Authenticated State)
Once the Web Auth Token is received, there are two possible scenarios:
Valid Token
Invalid Token (e.g., expired, banned, logged out, etc.)
Upon receiving the token, the website reinitializes by sending a message to the Chat Service via WebSocket.
If the authentication is valid, the website switches from Guest State → Authenticated State, enabling full access to chat features similar to the mobile app.
Mobile App: Logout Scenario
There are two scenarios when the mobile app triggers a logout:
The website is not connected (no user is currently connected via the website). They may connect in the future.
The website is connected, and the expectation is that the website will automatically log out in real time.
In the first scenario, when the user later opens the website, it will reinitialize its connection to the WebSocket. During the authentication step, the Auth Service will reject the request, signaling the website to return to Guest State.
In the second scenario, the process is similar to scanning the QR code. When the mobile app triggers a logout, the Auth Service notifies the Chat Service, which sends a signal to the active connection on the website, prompting it to log out. Check the picture below
That’s all for today. If you have a system design topic you're interested in, or any other interesting system design solution for specific topic, don't hesitate to let me know—I’d be more than happy to share them here.
Propose Topic For Next Post
Propose Your Solution