V2.0 Widgets - Drop-in Authentication

V2.0 Widgets provide a fully-managed authentication interface that runs in an iframe with zero frontend complexity. Unlike the standard API (v1.0), you get a complete OTP flow with built-in security and fraud detection.

Why Choose V2.0 Widgets

For a detailed comparison of V2.0 vs V1.0 vs upcoming V1.2, see the Authentication Methods overview.

How V2.0 Widgets Work

The authentication flow is simple and secure:

Step 1: Create Widget in Dashboard

Before integrating, create a widget in your Akedly dashboard.

Dashboard Navigation

1. Log in to your Akedly dashboard at https://app.akedly.io
2. Navigate to Widgets in the left sidebar
3. Click Create New Widget

Basic Settings

• Name

  Widget Name

  Type

  string

  Description

  Internal name for your reference (e.g., "Production Login Widget")

• Name

  Description

  Type

  string

  Description

  Optional description of where this widget is used

Branding Customization:

• Name

  Company Logo

  Type

  file

  Description

  Upload your logo (displayed at top of widget)

• Name

  Company Name

  Type

  string

  Description

  Your company name (shown in widget header)

• Name

  Primary Color

  Type

  string

  Description

  Main brand color for buttons and accents

• Name

  Secondary Color

  Type

  string

  Description

  Background and secondary UI elements

Callback URLs

V2.0 Widgets support two types of callbacks. See Pipeline Setup for detailed configuration, or navigate to Pipelines → Select your pipeline → Callback URLs.

https://yourapp.com/auth/callback

https://yourapp.com/auth/callback?status=success&transactionId=mtx_abc123&attemptId=attempt_xyz789×tamp=2025-01-16T12:00:00Z&meta_userId=user_12345&meta_orderId=order_abc789

https://yourapp.com/auth/callback?status=failed&error=INVALID_OTP&transactionId=mtx_abc123&attemptId=attempt_xyz789×tamp=2025-01-16T12:00:00.000Z&meta_userId=user_12345&meta_orderId=order_abc789

https://yourapp.com/api/webhooks/akedly

Frontend Redirect Query Parameters:

• Name

  status

  Type

  string

  Description

  "success" or "failed"

• Name

  transactionId

  Type

  string

  Description

  The transaction ID from the verification flow

• Name

  attemptId

  Type

  string

  Description

  The original attemptId you created

• Name

  timestamp

  Type

  string

  Description

  ISO 8601 timestamp of when authentication completed

• Name

  error

  Type

  string

  Description

  Error code (only present if status=failed)

• Name

  meta_*

  Type

  string

  Description

  Custom metadata fields from publicMetadata. Each key is prefixed with meta_. Object values are JSON stringified.

Security Settings

Configure captcha, rate limiting, and fraud protection in the widget security settings panel.

Captcha Settings

Protect your widget from automated attacks with built-in captcha verification.

• Name

  Enable Captcha

  Type

  boolean

  Description

  Always enabled by default. Captcha verification is mandatory for all widget interactions and cannot be disabled.

• Name

  Require Cloudflare Turnstile

  Type

  boolean

  Description

  Always enabled. Cloudflare Turnstile is required to protect your quotas and widgets from bot spam. This setting cannot be turned off to ensure maximum security against automated abuse.

Rate Limiting

Control authentication and OTP request limits to protect your widget from abuse. Rate limits are configured across three dimensions: per phone number, per device ID (fingerprinting), and per widget.

Widget Attempts

Widget attempts track iframe loads and authentication attempts, regardless of whether they pass captcha or fingerprinting. A failed captcha still counts as an attempt, even if no OTP is sent.

Per Phone Number Limits

Per Device ID Limits

Per Widget Limits

OTP Requests

OTP requests track actual One-Time Password deliveries. These limits apply only when an OTP is successfully sent to the user.

Per Phone Number Limits

Per Device ID Limits

Per Widget Limits

Cooldown Duration

Circuit Breaker

The circuit breaker is your final layer of defense that automatically suspends your widget when abnormal traffic patterns are detected. It works alongside captcha and rate limiting to provide comprehensive protection.

Why Circuit Breaker Matters:

• Blocks Coordinated DDoS Attacks: Detects and stops distributed attacks from multiple sources attempting to overwhelm your widget
• Protects Your Quota: Prevents sophisticated attacks from draining your API quota and incurring unexpected costs
• Last Line of Defense: Catches threats that bypass captcha and rate limiting (while rare, it's possible with advanced attack techniques)
• Automatic Recovery: Temporarily suspends the widget during attacks and automatically resumes normal operation when the threat subsides

After Widget Creation

Once you create the widget, you'll receive credentials needed for API integration:

• Name

  Widget ID

  Type

  string

  Description

  Internal identifier (e.g., widget_a1b2c3d4...)

• Name

  Public Key

  Type

  string

  Description

  Used in API requests (e.g., pk_x1y2z3...)

• Name

  Secret Key

  Type

  string

  Description

  Used to sign API requests with HMAC-SHA256

The widget secret will only be displayed once at creation. Make sure you copy it as seen in the screenshot. If you lose it, you'll need to regenerate a new secret from the dashboard. Store your secret key in environment variables. Never commit it to version control or expose it to frontend code.

Step 2: Backend - Create Attempt

Your backend is responsible for initiating the authentication flow by creating an "attempt". This is a server-side operation that must never be done from the frontend to protect your widget secret.

Understanding the Flow

Signature Generation (Language-Agnostic)

The signature is the most critical part. Here's how to generate it in any language:

{
  "apiKey": "YOUR_API_KEY",
  "publicKey": "YOUR_PUBLIC_KEY",
  "timestamp": 1234567890123,
  "phoneNumber": "+1234567890"
}

signature = HMAC-SHA256(secret, message)
output = hex_encode(signature)

API Reference

{
  "apiKey": "61b7fgxxxxxxxxxxxx", //Account API key
  "publicKey": "pk_xxxxxxxxxxxx", //Widget's public key
  "signature": "a1b2c3d4e5f6789...", //Secret key
  "timestamp": 170155235400,
  "verificationAddress": {
    "phoneNumber": "+201556645234", // MUST have country code
    "email": "user@example.com" //optional
  },
  "digits": 6, //choose between 4 or 6
  "publicMetadata": {
    //optional
    "userId": "user_12345",
    "orderId": "order_abc789"
  },
  "privateMetadata": {
    //optional - server-only
    "internalUserId": "internal_xyz"
  },
  "customHeaders": {
    //optional - forwarded in webhooks
    "X-Correlation-ID": "corr_abc123",
    "X-Internal-Source": "checkout-flow"
  }
}

{
  "status": "success",
  "data": {
    "attemptId": "attempt_a1b2c3d4e5f6...",
    "iframeUrl": "https://auth.akedly.io/auth?attemptId=...",
    "expiresAt": "2025-01-16T12:05:00.000Z",
    "publicMetadata": {
      "userId": "user_12345",
      "orderId": "order_abc789"
    }
  }
}

Custom Metadata

Attach custom data to verification attempts that gets returned in callbacks. This is useful for tracking users, orders, or sessions through the authentication flow.

{
  .........
  "publicMetadata": { //example of data sent to frontend
    "userId": "user_12345",
    "orderId": "order_abc789",
    "registerSource": "landing_page",
    "preferences": {
      "language": "en",
      "timezone": "UTC+2"
    }
  },
  "privateMetadata": { //example of server-only data
    "internalId": "internal_xyz",
    "sessionToken": "sess_abc123",
    "experimentGroup": "A",
    "sessionData": {
      "cartItems": 3,
      "lastLogin": "2025-01-15T10:00:00Z"
    }
  }
}

Implementation Examples

Complete code examples for creating an authentication attempt in popular backend languages.

const crypto = require('crypto')
const axios = require('axios')

// Environment variables (NEVER expose these in frontend)
const AKEDLY_API_KEY = process.env.AKEDLY_API_KEY
const WIDGET_PUBLIC_KEY = process.env.WIDGET_PUBLIC_KEY
const WIDGET_SECRET = process.env.WIDGET_SECRET

function generateSignature(apiKey, publicKey, secret, timestamp, phoneNumber) {
  const message = JSON.stringify({
    apiKey,
    publicKey,
    timestamp,
    phoneNumber,
  })

  return crypto.createHmac('sha256', secret).update(message).digest('hex')
}

async function createAuthAttempt(phoneNumber, email = null, metadata = {}) {
  const { publicMetadata, privateMetadata } = metadata
  const timestamp = Date.now()

  const signature = generateSignature(
    AKEDLY_API_KEY,
    WIDGET_PUBLIC_KEY,
    WIDGET_SECRET,
    timestamp,
    phoneNumber,
  )

  const response = await axios.post(
    'https://api.akedly.io/api/v1/widget-sdk/create-attempt',
    {
      apiKey: AKEDLY_API_KEY,
      publicKey: WIDGET_PUBLIC_KEY,
      signature,
      timestamp,
      verificationAddress: {
        phoneNumber,
        email,
      },
      digits: 6,
      publicMetadata,
      privateMetadata,
    },
  )

  return response.data.data // { attemptId, iframeUrl, expiresAt, publicMetadata }
}

// Usage in Express route
app.post('/api/auth/start', async (req, res) => {
  try {
    const { phoneNumber, email, userId, orderId } = req.body

    const attempt = await createAuthAttempt(phoneNumber, email, {
      publicMetadata: { userId, orderId },
      privateMetadata: { internalId: req.session.internalId },
    })

    res.json({
      success: true,
      attemptId: attempt.attemptId,
      iframeUrl: attempt.iframeUrl,
    })
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.response?.data || error.message,
    })
  }
})

Step 3: Frontend - Open Widget

Once you receive the attemptId and iframeUrl from your backend, open the Akedly authentication widget in an iframe or WebView.

Implementation Options

Option 1: Iframe in Modal/Dialog (Recommended for Web)

Open the widget in a modal dialog for the best user experience. The widget is designed to fit perfectly in a 500px × 700px iframe.

Option 2: WebView in Native App (Recommended for Mobile)

Use a WebView component in Flutter or React Native to display the widget with full native integration.

Option 3: Iframe in Page

Embed the widget directly in your page layout.

Handling Results

The widget communicates results through two mechanisms:

1. URL Redirect (if frontendCallbackURL is configured in pipeline)
2. PostMessage API (for web) or Navigation Detection (for WebViews)

import { useState, useEffect } from 'react'

export default function AuthModal() {
  const [isOpen, setIsOpen] = useState(false)
  const [iframeUrl, setIframeUrl] = useState('')
  const [loading, setLoading] = useState(false)

  const startAuth = async (phoneNumber, email = null) => {
    setLoading(true)

    try {
      const response = await fetch('/api/auth/start', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ phoneNumber, email }),
      })

      const data = await response.json()

      if (!data.success) {
        throw new Error(data.error)
      }

      setIframeUrl(data.iframeUrl)
      setIsOpen(true)
    } catch (error) {
      alert('Failed to start authentication: ' + error.message)
    } finally {
      setLoading(false)
    }
  }

  // Listen for postMessage from iframe
  useEffect(() => {
    const handleMessage = (event) => {
      if (event.origin !== 'https://auth.akedly.io') return

      if (event.data.type === 'AUTH_SUCCESS') {
        console.log('Authentication successful!', event.data)
        setIsOpen(false)
        onAuthSuccess(event.data)
      } else if (event.data.type === 'AUTH_FAILED') {
        alert('Authentication failed')
      }
    }

    window.addEventListener('message', handleMessage)
    return () => window.removeEventListener('message', handleMessage)
  }, [])

  const onAuthSuccess = (data) => {
    // Your success logic
    window.location.href = '/dashboard'
  }

  return (
    <>
      <button
        onClick={() => startAuth('+201234567890', 'user@example.com')}
        disabled={loading}
      >
        {loading ? 'Loading...' : 'Login with Phone'}
      </button>

      {isOpen && (
        <div
          style={{
            position: 'fixed',
            top: 0,
            left: 0,
            width: '100%',
            height: '100%',
            background: 'rgba(0, 0, 0, 0.5)',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            zIndex: 9999,
          }}
          onClick={(e) => {
            if (e.target === e.currentTarget) setIsOpen(false)
          }}
        >
          <iframe
            src={iframeUrl}
            style={{
              width: '500px',
              height: '700px',
              border: 'none',
              borderRadius: '12px',
              background: 'white',
              boxShadow: '0 10px 40px rgba(0, 0, 0, 0.3)',
            }}
          />
        </div>
      )}
    </>
  )
}

Step 4: Handle Callbacks

Backend Webhook Payload

If you configure a backendCallbackURL in your pipeline settings, Akedly sends a POST request to your server with complete verification details.

Webhook Timing:

The webhook is sent:

• Immediately after successful verification (OTP verified)
• Immediately after failed verification (invalid OTP, expired, etc.)

Success Webhook Structure:

{
  "status": "success",
  "timestamp": "2025-01-16T12:05:30.123Z",
  "widgetAttempt": {
    "attemptId": "attempt_a1b2c3d4e5f67890",
    "widgetId": "widget_x1y2z3",
    "userId": "67890abcdef12345",
    "status": "verified",
    "verificationAddress": {
      "phoneNumber": "+20****7890",
      "email": "user@example.com"
    },
    "otpConfig": {
      "digits": 6,
      "resendCount": 0
    },
    "createdAt": "2025-01-16T12:00:00.000Z",
    "expiresAt": "2025-01-16T12:05:00.000Z",
    "captchaVerifiedAt": "2025-01-16T12:01:15.500Z",
    "otpRequestedAt": "2025-01-16T12:01:30.200Z",
    "completedAt": "2025-01-16T12:05:30.123Z"
  },
  "transaction": {
    "transactionID": "ae2eacaebe3ed78b105498d5d0cfe54f",
    "status": "Successful",
    "verificationAddress": {
      "phoneNumber": "+201234567890",
      "email": "user@example.com"
    },
    "OTP": "123456",
    "creationDate": "2025-01-16T12:01:25.000Z",
    "expirationDate": "2025-01-16T12:04:25.000Z",
    "updateDate": "2025-01-16T12:05:30.123Z",
    "userID": "67890abcdef12345",
    "pipelineID": "abc123pipeline"
  },
  "transactionReq": {
    "_id": "req_9876543210",
    "status": "Successful",
    "mainTransactionID": "ae2eacaebe3ed78b105498d5d0cfe54f",
    "sentVerification": true,
    "creationDate": "2025-01-16T12:01:30.000Z",
    "expirationDate": "2025-01-16T12:04:30.000Z",
    "sentVerificationDate": "2025-01-16T12:01:31.500Z",
    "inputOTP": "123456",
    "verificationDate": "2025-01-16T12:05:30.123Z"
  },
  "publicMetadata": {
    "userId": "user_12345",
    "orderId": "order_abc789"
  },
  "privateMetadata": {
    "internalUserId": "internal_xyz",
    "sessionToken": "sess_secret_token"
  }
}

Security Features

V2.0 Widgets include enterprise-grade security features at no additional cost. Our multi-layered approach combines visible and invisible protection mechanisms.

Error Reference

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "retryable": true, // Optional: whether user can retry
  "retryAfter": "ISO8601", // Optional: when to retry (for rate limits)
  "cooldownSeconds": 60, // Optional: seconds until retry allowed
  "details": {} // Optional: additional context
}

HTTP Status Codes

Authentication & Security Errors

Rate Limiting Errors

All rate limit errors include retryAfter (ISO8601 timestamp) and cooldownSeconds (integer).

Circuit Breaker Errors

External Service Errors

Advanced Features

Bring Your Own OTP

If you want to generate your own OTP codes, pass a custom otp parameter:

const response = await axios.post(
  'https://api.akedly.io/api/v1/widget-sdk/create-attempt',
  {
    apiKey: AKEDLY_API_KEY,
    publicKey: WIDGET_PUBLIC_KEY,
    signature,
    timestamp,
    verificationAddress: { phoneNumber: '+201234567890' },
    otp: '123456', // Your custom 6-digit OTP
  },
)

Troubleshooting

INVALID_SIGNATURE Error

Common causes:

• Incorrect HMAC algorithm (must be SHA256)
• Wrong JSON key order in signature message
• Extra spaces in JSON string
• Widget secret is incorrect
• Timestamp is stale (>5 minutes old)

Solutions:

• Verify you're using HMAC-SHA256
• Ensure message format is JSON.stringify({ apiKey, publicKey, timestamp, phoneNumber })
• Check your widget secret matches the dashboard
• Synchronize server clock with NTP

Iframe Shows Blank Screen

Common causes:

• Invalid or malformed attemptId in URL
• Attempt has expired (5-minute lifetime)
• Parent page not served over HTTPS
• Browser blocking mixed content

Solutions:

• Check browser console for errors
• Verify iframeUrl contains a valid attemptId
• Ensure parent page uses HTTPS in production
• Confirm attempt hasn't expired

PIPELINE_NOT_CONFIGURED Error

Solution:

• Go to Dashboard → Widgets → [Your Widget]
• Edit widget settings
• Select a pipeline from the dropdown
• Save changes

OTP Not Received

Common causes:

• Phone number format is incorrect
• Rate limit exceeded for phone number
• Pipeline verification methods not configured

Solutions:

• Ensure phone number uses E.164 format with country code (e.g., +201234567890)
• Check rate limit status in dashboard analytics
• Verify pipeline has at least one verification method enabled

Support & Resources

Getting Help

• Dashboard: https://app.akedly.io
• Support: support@akedly.io
• Co-founders: muhad@akedly.io, hana@akedly.io

Additional Resources

• Quickstart Guide
• V1.0 Standard API

Version: 2.0.0 Last Updated: January 11th, 2026 API Base URL: https://api.akedly.io/api/v1/widget-sdk