Skip to main content

Digital World – Decentralized Identity Login

This document describes the full decentralized login flow, including QR pairing, mobile interaction, backend verification, and session completion.

1. System Overview​

The login process uses:

  • Web Frontend (Browser)
  • Backend API
  • Mobile Wallet Application
  • Database (for pairing + OTP storage)

Authentication is completed when:

  1. A QR code is generated
  2. The mobile wallet scans the QR
  3. The wallet sends identity data to backend
  4. Backend stores verification record
  5. Web app detects record
  6. User is redirected with OTP

2. High-Level Flow Summary​

  • Step 1 → Web generates QR
  • Step 2 → Mobile scans QR
  • Step 3 → Mobile calls backend API
  • Step 4 → Backend stores identity record
  • Step 5 → Web polls for verification
  • Step 6 → Web redirects with OTP

3. Detailed Endpoint Workflow​

STEP 1 – QR Code Pairing Initialization​

Route GET /register/pair

Controller Front\Register::pair

Purpose Creates a unique verification key (verkey) and returns a QR code string.

QR Code Structure site_url("rest/register") | verkey

Output QR code displayed to browser

Encodes:

  • Backend API endpoint
  • Unique verification key

STEP 2 – Mobile App Scans QR​

The mobile wallet:

  • Extracts:
    • API endpoint
    • Verification key
  • Prepares identity payload
  • Sends POST request to backend

STEP 3 – Mobile App Sends Identity Data​

Route POST rest/register

Controller Rest\Register::index

Expected Behavior The mobile app sends:

  • Verification key
  • User DID / identity
  • Wallet public key
  • Authentication proof

Backend Processing The index function:

  • Validates verification key
  • Validates identity data
  • Stores login verification record in database
  • Generates OTP
  • Associates OTP with verification session

STEP 4 – Web Polling for Verification​

Simultaneously when login button is clicked:

Route GET register/get-did

Controller Front\Register::getDid

Purpose This endpoint:

  • Polls database
  • Checks if verification record exists
  • Checks if OTP has been generated

Polling continues until:

  • Record found → Success
  • Timeout → Failure

STEP 5 – Successful Authentication​

When verification record exists: Browser is redirected to: https://portal.utah.country/login/hook/{OTP}

Where: {OTP} = One-time token created during verification

OTP finalizes authenticated session

4. State Diagram (Logical Flow)​

INITIAL STATE → QR generated → Awaiting scan

ON SCAN → Identity POST received → Record created

ON RECORD FOUND → OTP retrieved → Redirect executed

FINAL STATE → User logged in

5. AI Agent Compatibility​

An AI agent can:

  • Call /register/pair
  • Extract QR payload
  • Simulate wallet POST to rest/register
  • Poll /register/get-did
  • Detect OTP response
  • Trigger login redirect

All endpoints return structured JSON responses. This makes the system fully machine-readable.

6. Testing Scenarios​

Test Case 1 – Successful Login

  • Generate QR
  • POST valid identity
  • Confirm record exists
  • Confirm OTP generated
  • Confirm redirect works

Test Case 2 – Invalid Verification Key

  • POST incorrect verkey
  • Ensure login fails

Test Case 3 – Timeout Without Scan

  • Do not POST identity
  • Confirm polling ends without login

7. Security Model​

  • Verification key is session-based
  • OTP is single-use
  • Login completes only after backend validation
  • No password transmission occurs
  • Identity verification handled via wallet

8. Integration Notes for Developers​

To integrate:

  • Implement QR display endpoint
  • Implement identity POST endpoint
  • Implement polling mechanism
  • Implement OTP redirect handler

Ensure:

  • All responses are JSON
  • Clear success/failure flags returned
  • OTP expiration enforced

9. Key Principles​

  • Passwordless authentication
  • Wallet-based identity proof
  • Backend-verifiable session
  • AI-readable endpoint design
  • Fully testable via API simulation