Login via OTP Code Device Pairing

The Passwordless Login with OTP 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 OTP codes.

• 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 OTP Code from Device A

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

   • Authorization: Auth-Key of Device A

   • Response: ID and code of OTP.

2. Display OTP Code to Device B

   • Device B input the OTP code.

3. Device A approves pairing

   • Endpoint: POST /api/v1/users/auth/passwordless/otp/:otpCode/approve

   • Response: { status: "Approved" }.

4. Device B polls pairing status

   • Endpoint: GET /api/v1/users/auth/passwordless/otp/:otpCode

   • Status updates to APPROVED after confirmation by Device A.

5. Device B logs in

   • Endpoint: POST /api/v1/users/auth/passwordless/otp/:otpCode/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 OTP Code

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

   • Authentication: No authentication required.

   • Headers:

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

   • Response: ID and code of OTP.

2. Device B polls OTP code status

   • Endpoint: GET /api/v1/users/auth/passwordless/otp/:otpCode

   • Poll interval: ~3 seconds.

   • Waits until status=Approved.

3. Device A approves pairing

   • Endpoint: POST /api/v1/users/auth/passwordless/otp/:otpCode/approve

   • Authorization: Auth-Key of Device A.

   • Status is updated to APPROVED.

4. Device B completes login

   • Endpoint: POST /api/v1/users/auth/passwordless/otp/:otpCode/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 OTP code generation, the server will send a push notification (data message) to that device after the OTP is approved.

Push Notification Payload Example:

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

Security Considerations

• OTP 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 OTP 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.