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.

MessageDirectionMeans
qrLoginRequestpage → your serverGive me a sign-in code.
SessionRequestedyour server → pageHere's the QR link and when it expires.
loginSuccessyour server → pageSomeone approved; here's the session.
requestRejectedyour server → pageThey tapped Not me.
requestExpiredyour server → pageThe 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.

sign-in pageJavaScript
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.

server.jsJavaScript
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));
});
FieldTypeWhat it is
requestIdstringRandom, at least 122 bits. A UUID v4 is fine. Made by your server, never sent by the page.
socketconnectionThe page that asked. Only it hears the outcome.
ip, locationstringWhere 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.
userAgentstringThe 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.
expiresUnix secondsWhen the code dies. 90 seconds matches what the app tells people.

The token is your API key and the request ID as JSON, Base64-encoded. Decoded, it's just:

token, decodedJSON
{
  "apikey": "YOUR_API_KEY",
  "requestId": "1b4e28ba-2fa1-41d2-883f-0016d3cca427"
}
  • The host must be auth.orvixtech.com and 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, and requestId.
  • 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 qrValue with 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

sign-in pageJavaScript
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 →