Step 1 of 2
Show the sign-in code
Your sign-in page opens a WebSocket to your server and asks for a code. Your server creates the request, keeps the socket with it, and sends back the QR link. When OT Auth reports the outcome, the answer goes down that same socket.
| Message | Direction | Means |
|---|---|---|
qrLoginRequest | page → your server | Give me a sign-in code. |
SessionRequested | your server → page | Here's the QR link and when it expires. |
loginSuccess | your server → page | Someone approved; here's the session. |
requestRejected | your server → page | They tapped Not me. |
requestExpired | your server → page | The code died; ask for a new one. |
These messages travel between your page and your own server, so the names are yours to choose. OT Auth never sees them.
1. Ask from the sign-in page
Open the socket when the page loads, and ask for a code as soon as it connects.
const socket = new WebSocket("wss://acme.example/api/ws");
socket.onopen = () =>
socket.send(JSON.stringify({ MessageType: "qrLoginRequest" }));2. Create the request on your server
One record per code, kept until the code is used, rejected or expired. The socket is part of the record: it is how the answer finds its way back to this page and no other. Keep one live code per page: when a page asks again, retire its old code first, so a code someone photographed earlier stops working.
Accept the socket only from your own sign-in page, by its Origin header. Browsers always send it, and a page can't change it. Without that check, a page on another site could open your socket from its visitor's browser: the phone would show the visitor's own IP address and city, and that site's script would receive the session when they approve.
import { WebSocketServer } from "ws";
import { randomUUID } from "node:crypto";
const TTL = 90; // seconds; what people see in the app's countdown
const SIGN_IN_PAGE = "https://acme.example"; // the origin of your sign-in page
const wss = new WebSocketServer({ server, path: "/api/ws", maxPayload: 4096 });
wss.on("connection", (socket, req) => {
if (req.headers.origin !== SIGN_IN_PAGE) return socket.close(1008);
const ip = clientIp(req); // from the connection, not the page
const userAgent = req.headers["user-agent"] ?? "";
socket.on("message", (raw) => {
let message;
try {
message = JSON.parse(raw);
} catch {
return; // not JSON: ignore it
}
if (message?.MessageType !== "qrLoginRequest") return;
dropRequestsOf(socket); // one live code per page
const requestId = randomUUID(); // always made here
const expireTime = Math.floor(Date.now() / 1000) + TTL;
requests.set(requestId, { socket, ip, userAgent, location: lookupCity(ip), expires: expireTime });
setTimeout(() => expire(requestId), TTL * 1000);
const token = Buffer.from(
JSON.stringify({ apikey: process.env.OTAUTH_API_KEY, requestId }),
).toString("base64url");
socket.send(JSON.stringify({
message: "SessionRequested",
qrValue: `https://auth.orvixtech.com/qr-login?token=${token}`,
expireTime,
expireDuration: TTL,
}));
});
// A closed page can't be signed in: drop its requests.
socket.on("close", () => dropRequestsOf(socket));
});| Field | Type | What it is |
|---|---|---|
requestId | string | Random, at least 122 bits. A UUID v4 is fine. Made by your server, never sent by the page. |
socket | connection | The page that asked. Only it hears the outcome. |
ip, location | string | Where the page connected from, as your server sees it. OT Auth shows both to the person before they approve. The city lookup can run in the background: store the pending lookup and wait for it in /qrvalidate, so the QR code isn't held up. |
userAgent | string | The page's browser, from the socket's request headers. Keep it for the session you create: OT Auth's later calls come from OT Auth's server, not from this browser. |
expires | Unix seconds | When the code dies. 90 seconds matches what the app tells people. |
3. The link inside the code
The token is your API key and the request ID as JSON, Base64-encoded. Decoded, it's just:
{
"apikey": "YOUR_API_KEY",
"requestId": "1b4e28ba-2fa1-41d2-883f-0016d3cca427"
}- The host must be
auth.orvixtech.comand the path/qr-login. The app refuses any other link with “This code isn't for OT Auth”. - The keys are
apikey, all lower case, andrequestId. - Use URL-safe Base64 (
base64url). Standard Base64 works too, but its+and/need escaping in a URL. - Nothing else is needed: the app gets the details from your server through /qrvalidate.
4. Show it
- Draw the QR code from
qrValuewith any QR library: dark on light, at least 200 × 200 px, error correction level M (medium, the default in most QR libraries). It still scans through glare on the screen, and the code stays easy for a camera to read. - Show a countdown to
expireTime, so people know why a code stopped working. - On a phone, show the same link as a button, such as Open OT Auth App. With OT Auth installed, it opens the app straight onto the approval screen.
5. Listen for the outcome
socket.onmessage = ({ data }) => {
const m = JSON.parse(data);
switch (m.message) {
case "SessionRequested":
showQr(m.qrValue); // and the same link as a button on phones
startCountdown(m.expireTime);
break;
case "loginSuccess":
saveSession(m.data); // whatever your server put in it
location.assign("/dashboard");
break;
case "requestRejected":
showMessage("Sign-in was declined on the phone.");
break;
case "requestExpired":
showMessage("That code expired."); // ask again for a fresh one
break;
}
};On requestRejected or requestExpired, offer a fresh code: send qrLoginRequest again on the same socket. Never extend an old request.
Next, answer OT Auth's calls: Callback reference →