Login via QR Code Device Pairing

The Passwordless Login with QR Code Device Pairing feature allows users to securely authenticate without a password by pairing a new device with an already authenticated device. This mechanism supports bidirectional pairing:

1. From a logged-in device to a new device

2. From a new device to a logged-in device

Key benefits:

• Strong security using short-lived QR codes and device-specific authorization tokens.

• Seamless user experience with minimal interaction.

• Device management through X-Device-* headers for device metadata.

Flow 1 – Logged-in Device Initiates Pairing

This flow is initiated from a logged-in device (Device A) to authorize a new device (Device B).

Sequence Diagram

Step-by-Step Description

1. Generate QR Code from Device A

   • Endpoint: POST /api/v1/users/auth/passwordless/qrcode/generate

   • Authorization: Auth-Key of Device A

   • Response: ID and qrCodeBase64 of QR code.

2. Display QR Code to Device B

   • Device B scans the QR code locally.

   • The QR code encodes the pairing QR code ID.

3. Device A approves pairing

   • Endpoint: POST /api/v1/users/auth/passwordless/qrcode/:qrCodeId/approve

   • Response: { status: "Approved" }.

4. Device B polls pairing status

   • Endpoint: GET /api/v1/users/auth/passwordless/qrcode/:id

   • Status updates to APPROVED after confirmation by Device A.

5. Device B logs in

   • Endpoint: POST /api/v1/users/auth/passwordless/qrcode/:id/login

   • Headers: X-Device-* for device metadata.

   • Response: { authKey, refreshAuthKey }.

Flow 2 – New Device Initiates Pairing

This flow allows a new device (Device B) to initiate pairing, which is approved by the logged-in device (Device A).

Sequence Diagram

Step-by-Step Description

1. Device B generates QR Code

   • Endpoint: POST /api/v1/users/auth/passwordless/qrcode/generate

   • Authorization: No authentication required.

   • Headers:

     • X-Device-Token : Used to send a push notification via data message after the QR code is successfully approved.

   • Response: ID and qrCodeBase64 of QR code.

2. Device B polls QR code status

   • Endpoint: GET /api/v1/users/auth/passwordless/qrcode/:id

   • Poll interval: ~3 seconds.

   • Waits until status=Approved.

3. Device A approves pairing

   • Endpoint: POST /api/v1/users/auth/passwordless/qrcode/:qrCodeId/approve

   • Authorization: Auth-Key of Device A.

   • Status is updated to APPROVED.

4. Device B completes login

   • Endpoint: POST /api/v1/users/auth/passwordless/qrcode/:id/login

   • Headers: X-Device-* for device metadata.

   • API responds with authentication tokens and upserts device record.

📔 Notes: If the client includes the X-Device-Token header during QR code generation, the server will send a push notification (data message) to that device after the QR is approved.

Push Notification Payload Example:

{
    "id": "4f7e124d-0f46-4a5b-a0c8-1fd88a3b3ca3",
    "status": "Approved",
    "approvedAt": "2025-08-19T07:57:35.0092387Z"
}

Security Considerations

• QR codes are single-use and time-limited to prevent replay attacks.

• Auth-Key ensures device-level authorization for approval actions.

• Tokens (authKey & refreshKey) are issued only after pairing confirmation.

• Device metadata headers (X-Device-*) are required to register the device securely.

---

Summary

The QR code-based passwordless login mechanism enables secure, bidirectional device pairing. Users can:

• Authorize new devices from a logged-in device.

• Initiate pairing from a new device and have it approved by an existing device.

This system ensures security, ease of use, and full device traceability.