OTP Authentication

Production-grade one-time password authentication with a separate otp_codes table, code expiration, single-use enforcement, and brute-force protection.

What You'll Build

A single API endpoint that handles four actions through one workflow:

Endpoint: POST /api/v1/YOUR_ID/otp

Request body:

{
  "email": "user@example.com",
  "action": "enable",
  "code": ""
}

The code field is only needed for the verify action. For enable and send, send it as an empty string.

Database Setup

You need one new table and one new column on the existing users table.

New table: otp_codes

Add column to users

No OTP codes or secrets are stored on the user row. The otp_enabled flag just tells the login workflow whether to require OTP.

Workflow Flow

Flow Start
  → Data Validator (email)
    ├─ TRUE  → Query Data (users)  ─┐
    │         Query Data (otp_codes) ─┤
    │                                 → Code (route + validate)
    │                                   → Condition (route?)
    │                                     IF (insert_email)      → Write Data (INSERT otp_codes) → HTTP Request (Resend) → Simple Output
    │                                     ELSE IF (insert_user)  → Write Data (INSERT otp_codes) → Write Data (UPDATE users) → Simple Output
    │                                     ELSE IF (update_otp)   → Write Data (UPDATE otp_codes) → Simple Output
    │                                     ELSE (no_write)        → Simple Output
    └─ FALSE → Simple Output (400 error)

The old workflow used 4 Condition nodes with boolean flags. This version uses a single route string and one multi-branch Condition, cutting the node count significantly.

Step 1 - Flow Start

Step 2 - Data Validator

Validates the incoming email before any database queries run. Rejects malformed requests early.

Output variable: dataValidator

Schema:

Branches:

Step 3a - Query Data (Find User)

Look up the user to check if they exist and whether OTP is already enabled. Runs in parallel with Step 3b.

Output variable: user_data

Step 3b - Query Data (Latest OTP Code)

Fetch the most recent unused OTP code for this user. Runs in parallel with Step 3a. This is needed for the verify action to check the code against.

Output variable: latest_otp

We filter by used = 0 to only get active (unused) codes. Enable/disable rows are inserted with used = 1 so they never interfere with this query.

Step 4 - Code Node (Route + Validate)

Both Query Data nodes feed into this single Code node.

All business logic lives in this single Code node. Based on the action parameter, it validates the request and returns a route string that controls which branch the single Condition takes.

Output variable: otp_result

(function() {
  const email = variables.email;
  const action = variables.action;
  const code = variables.code;

  const userData = [{{user_data}}][0] || {};
  const users = userData.rows || [];
  const user = users.find(u => u.email === email);

  if (!user) {
    return {
      route: 'no_write',
      response: { success: false, error: 'User not found' }
    };
  }

  if (!['enable', 'send', 'verify', 'disable'].includes(action)) {
    return {
      route: 'no_write',
      response: { success: false, error: 'Invalid action' }
    };
  }

  const otpData = [{{latest_otp}}][0] || {};
  const otpRows = otpData.rows || [];
  const latestCode = otpRows.length > 0 ? otpRows[0] : null;

  const now = String(Date.now());

  // --- ENABLE ---
  if (action === 'enable') {
    if (user.otp_enabled === 'yes') {
      return {
        route: 'no_write',
        response: { success: false, error: 'OTP is already enabled' }
      };
    }
    return {
      route: 'insert_user',
      email: user.email,
      name: user.name,
      otp_code: '',
      otp_action: 'enable',
      created_at: now,
      otp_used: '1',
      otp_enabled: 'yes',
      response: { success: true, message: 'OTP has been enabled.' }
    };
  }

  // --- DISABLE ---
  if (action === 'disable') {
    if (user.otp_enabled !== 'yes') {
      return {
        route: 'no_write',
        response: { success: false, error: 'OTP is not enabled' }
      };
    }
    return {
      route: 'insert_user',
      email: user.email,
      name: user.name,
      otp_code: '',
      otp_action: 'disable',
      created_at: now,
      otp_used: '1',
      otp_enabled: 'no',
      response: { success: true, message: 'OTP has been disabled.' }
    };
  }

  // --- SEND ---
  if (action === 'send') {
    if (user.otp_enabled !== 'yes') {
      return {
        route: 'no_write',
        response: { success: false, error: 'OTP is not enabled' }
      };
    }
    const newCode = String(Math.floor(100000 + Math.random() * 900000));
    return {
      route: 'insert_email',
      email: user.email,
      name: user.name,
      otp_code: newCode,
      otp_action: 'login',
      created_at: now,
      response: { success: true, message: 'OTP code sent to your email.' }
    };
  }

  // --- VERIFY ---
  if (action === 'verify') {
    if (user.otp_enabled !== 'yes') {
      return {
        route: 'no_write',
        response: { success: false, error: 'OTP is not enabled' }
      };
    }

    if (!latestCode) {
      return {
        route: 'no_write',
        response: { success: false, error: 'No active OTP code found' }
      };
    }

    const attempts = parseInt(latestCode.attempts || '0', 10);
    if (attempts >= 5) {
      return {
        route: 'no_write',
        response: { success: false, error: 'Too many attempts. Request a new code.' }
      };
    }

    const createdAtMs = parseInt(latestCode.created_at, 10);
    const fiveMin = 5 * 60 * 1000;
    if (isNaN(createdAtMs) || Date.now() - createdAtMs > fiveMin) {
      return {
        route: 'update_otp',
        email: user.email,
        otp_code: latestCode.code,
        otp_used: '1',
        otp_attempts: String(attempts),
        created_at: latestCode.created_at,
        response: { success: false, error: 'OTP code has expired. Request a new one.' }
      };
    }

    if (!code || code !== latestCode.code) {
      return {
        route: 'update_otp',
        email: user.email,
        otp_code: latestCode.code,
        otp_used: '0',
        otp_attempts: String(attempts + 1),
        created_at: latestCode.created_at,
        response: { success: false, error: 'Invalid OTP code' }
      };
    }

    return {
      route: 'update_otp',
      email: user.email,
      otp_code: latestCode.code,
      otp_used: '1',
      otp_attempts: String(attempts),
      created_at: latestCode.created_at,
      response: { success: true, message: 'OTP verified successfully' }
    };
  }
})();

Security: Every return includes a response object that contains ONLY what the client should see. Internal fields like otp_code, email, route, etc. stay on the server. All Simple Output nodes reference {{otp_result.response}}.

Route values

What each action returns

Step 5 - Condition (route?)

A single multi-branch Condition replaces the old 4-Condition chain. Uses AND conditions to match the route value.

Step 6a - Write Data (INSERT otp_codes) - Send path

This runs for the send action (insert_email route). Inserts a new row with the generated code, then sends the email.

Step 6a.1 - HTTP Request (Send OTP Email)

Body:

{
  "from": "YourApp <noreply@yourdomain.com>",
  "to": "{{otp_result.email}}",
  "subject": "Your OTP Code",
  "html": "<h2>Hi {{otp_result.name}},</h2><p>Your one-time password is:</p><h1 style='letter-spacing:8px;font-size:36px;'>{{otp_result.otp_code}}</h1><p>This code expires in 5 minutes and can only be used once.</p>"
}

Step 6a.2 - Simple Output (Send success)

Step 6b - Write Data (INSERT otp_codes) - Enable/Disable path

This runs for enable/disable actions (insert_user route). Same INSERT as 6a but with used set to 1 since these are audit records, not verifiable codes.

Step 6b.1 - Write Data (UPDATE users)

Update the user's otp_enabled flag.

Step 6b.2 - Simple Output (Enable/Disable success)

Step 6c - Write Data (UPDATE otp_codes) - Verify path

This runs for the verify action (update_otp route). Updates the existing code row to mark it as used or increment the attempt counter.

Where (to find the exact row):

Columns to update:

Step 6c.1 - Simple Output (Verify result)

Step 6d - Simple Output (No write / Error)

The ELSE branch - handles all error cases where no database write is needed.

Security Features

Testing

Using curl

Test 1 - Enable OTP:

curl -X POST https://workflow.ubex.ai/api/v1/YOUR_ID/otp \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "action": "enable", "code": ""}'

Expected: { "success": true, "message": "OTP has been enabled." }

Test 2 - Disable OTP:

curl -X POST https://workflow.ubex.ai/api/v1/YOUR_ID/otp \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "action": "disable", "code": ""}'

Expected: { "success": true, "message": "OTP has been disabled." }

Test 3 - Send new code:

curl -X POST https://workflow.ubex.ai/api/v1/YOUR_ID/otp \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "action": "send", "code": ""}'

Expected: { "success": true, "message": "OTP code sent to your email." }

The OTP code is NOT in the response. Check your email.

Test 4 - Verify with wrong code:

curl -X POST https://workflow.ubex.ai/api/v1/YOUR_ID/otp \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "action": "verify", "code": "000000"}'

Expected: { "success": false, "error": "Invalid OTP code" }

Test 5 - Verify with correct code:

curl -X POST https://workflow.ubex.ai/api/v1/YOUR_ID/otp \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "action": "verify", "code": "THE_REAL_CODE"}'

Expected: { "success": true, "message": "OTP verified successfully" }

Edge cases

Integration with Login

To make OTP work with your login workflow, you need two changes. See the User Login tutorial for the full updated code.

If you also have TOTP (Google Authenticator) enabled, TOTP takes priority over email OTP during login. See the Google Authenticator (TOTP) tutorial for details on how both methods work together.

Changes to the login workflow

1. Query Data (Step 4) - Add otp_enabled to the columns list
2. Code Node (Step 5) - After password and email verification pass, add:

if (user.otp_enabled === 'yes') {
  return {
    success: false,
    otp_required: true,
    message: 'OTP verification required'
  };
}

3. Condition (Step 6) - Both IF and ELSE branches should return status 200

Frontend flow

1. User enters email + password, clicks "Sign in"
2. Login returns { success: false, otp_required: true }
3. Frontend shows the OTP code input
4. Frontend calls /otp with action: "send" to trigger the email
5. User enters the 6-digit code from their email
6. Frontend calls /otp with action: "verify" with the code
7. On success → user is authenticated

Security Checklist