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 V1.2, V2.0, and V1.0, 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. In the left sidebar, open Authentication → Setup → Widgets
3. Click Create Widget (the button reads Create Your First Widget on the empty state)

Basic Info

The widget form is split into collapsible sections, navigated from the Sections rail: Basic Info, Pipeline, Passkeys, Captcha, Rate Limiting, Circuit Breaker, and Developer.

• 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

Branding is not configured in the widget form. The form only carries a Branding & theme link card; the appearance of the hosted widget is edited in the dedicated Branding Studio at /admin/widgets/:id/branding, which has a live preview alongside its tabs.

• Name

  Brand

  Type

  tab

  Description

  Logo, brand name, and core brand colors.

• Name

  Theme

  Type

  tab

  Description

  Light/dark theme, surfaces, borders, and radii.

• Name

  Typography

  Type

  tab

  Description

  Font family and type scale.

• Name

  Layout

  Type

  tab

  Description

  Spacing, alignment, and overall widget composition.

• Name

  Components

  Type

  tab

  Description

  Per-component styling (buttons, inputs, and other controls).

• Name

  Content

  Type

  tab

  Description

  Widget copy — headings, labels, and helper text.

Rather than starting from a blank theme, the Brand tab offers presets — Akedly, Midnight, Minimal, Corporate and Playful. Pick one as a starting point and fine-tune from there; your custom copy is kept when you switch preset.

The preview beside the tabs is live and renders the real widget: loading, OTP entry, success and error always, plus the captcha and passkey screens when those are enabled on the widget. Toggle Show all screens to see them side by side, and switch the preview between desktop, tablet and mobile — each renders at that device's real width, so the hosted widget's own responsive behaviour is what you see. Edits are not applied until you press Save; Reset discards them and returns to the last saved branding.

Branding is a per-widget setting, so a widget must exist before you can open its Branding Studio. Create the widget first, then open it and follow the Branding & theme card.

Webhooks

V2.0 Widgets support two types of callbacks. See Pipeline Setup for detailed configuration, or navigate to Authentication → Setup → 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

  isTest

  Type

  string

  Description

  "true" on a successful test-pair redirect; omitted for production verifications.

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

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

Per device ID

Per widget

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

Per device ID

Per widget

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

  Widget Secret (SAVE THIS NOW)

  Type

  string

  Description

  Used to sign API requests with HMAC-SHA256

The secret is shown once and cannot be rotated

The widget secret is displayed only at creation — copy it then, as shown in the screenshot. There is no regenerate or rotate action for a widget secret anywhere in the product, so losing it is not self-service recoverable: you would have to create a new widget (and repoint your integration to its new public key) or contact support@akedly.io.

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, 5 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"
  }
}

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 }
}

// 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 widget — in an iframe on the web, or in a system browser in a mobile native app. Do not load it in a raw WebView (see Mobile native apps below).

Implementation Options

Web — iframe. Embed the widget in an iframe, in a modal/dialog (recommended) or inline in your page. It fits a 500px × 700px iframe. For passkeys, add the allow attribute — see Passkeys.

Web — full-page redirect (no iframe). Prefer not to embed? Send the whole browser tab to the iframeUrl. When the user finishes, the widget redirects back to your pipeline's Front-end Redirect URL with the same query parameters — so there's nothing to wire up beyond that one pipeline setting. A top-level page also has WebAuthn permission natively, so passkeys work with nothing to add (the allow attribute is iframe-only). Good when an iframe is awkward (CSP, small screens) or you just prefer a hosted page. See the snippet below.

Mobile native apps — a system browser (required). Open the widget in ASWebAuthenticationSession or SFSafariViewController (iOS), or Chrome Custom Tabs (Android) — never a raw WKWebView / Android WebView. See the Mobile native apps section below for why and how.

Handling Results

How the result reaches you depends on the surface:

1. Web (iframe) — listen for the postMessage AUTH_SUCCESS event, and/or use the redirect to your pipeline's Front-end Redirect URL.
2. Web (full-page redirect) — no iframe means no postMessage; the result comes purely from the redirect to your pipeline's Front-end Redirect URL.
3. Mobile native (system browser) — there is no parent window, so postMessage does not apply. Use the redirect to your pipeline's Front-end Redirect URL (a deep link your app intercepts).

The redirect carries status, transactionId, attemptId, timestamp, and any meta_* parameters in the query string. A successful test-pair redirect also carries isTest=true (configured per pipeline — see Pipeline Setup).

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}
            // Optional: enable passkeys (see /authentication/passkeys)
            allow="publickey-credentials-get *; publickey-credentials-create *"
            style={{
              width: '500px',
              height: '700px',
              border: 'none',
              borderRadius: '12px',
              background: 'white',
              boxShadow: '0 10px 40px rgba(0, 0, 0, 0.3)',
            }}
          />
        </div>
      )}
    </>
  )
}

Mobile native apps — open in a system browser

Why a system browser is required

Which API to use

Whatever stack you're on, it's the same two OS APIs underneath — so the rule never changes: open auth.akedly.io in the framework's system-browser / auth-session API (not its embedded WebView), and read the result from your callback. See Other frameworks below for Capacitor/Ionic, Cordova, .NET MAUI, and the fallback for anything not listed.

Result handling on native

There is no parent window in a system browser, so postMessage does not apply. Instead, set your pipeline's Frontend Callback URL (Authentication → Setup → Pipelines → your pipeline → Callback URLs) to a URL your app intercepts — typically a custom-scheme deep link such as myapp://akedly/callback. When verification completes, the widget redirects the browser to that URL with the usual query parameters (status, transactionId, attemptId, timestamp, and any meta_*); the OS hands the URL back to your app and closes the browser. A custom scheme needs no domain association; an https Universal Link / App Link works too but requires its own OS association (AASA on iOS, Digital Asset Links on Android).

import AuthenticationServices
import UIKit // for the presentationAnchor (UIApplication / UIWindowScene)

final class AkedlyAuth: NSObject, ASWebAuthenticationPresentationContextProviding {
  private var session: ASWebAuthenticationSession?

  /// `iframeUrl` is the URL your backend returned from create-attempt.
  /// `callbackScheme` is your app's custom scheme, e.g. "myapp".
  /// Set your pipeline's Front-end Redirect URL to "<scheme>://akedly/callback".
  func start(iframeUrl: URL,
             callbackScheme: String,
             onResult: @escaping (Result<URL, Error>) -> Void) {
    let session = ASWebAuthenticationSession(
      url: iframeUrl,
      callbackURLScheme: callbackScheme
    ) { callbackURL, error in
      if let callbackURL { onResult(.success(callbackURL)) }
      else if let error { onResult(.failure(error)) }
    }
    session.presentationContextProvider = self
    session.prefersEphemeralWebBrowserSession = false // share cookies + passkeys
    self.session = session
    session.start()
  }

  func presentationAnchor(for s: ASWebAuthenticationSession) -> ASPresentationAnchor {
    UIApplication.shared.connectedScenes
      .compactMap { ($0 as? UIWindowScene)?.keyWindow }.first ?? ASPresentationAnchor()
  }
}

// Usage — retain the helper for the session's lifetime. A temporary would be
// deallocated when this function returns, cancelling the flow; store it (e.g. a
// `var akedlyAuth: AkedlyAuth?` property on your view controller):
self.akedlyAuth = AkedlyAuth()
self.akedlyAuth?.start(iframeUrl: iframeUrl, callbackScheme: "myapp") { result in
  switch result {
  case .success(let url):
    let items = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems
    let status = items?.first { $0.name == "status" }?.value // "success" / "failed"
    // read transactionId, attemptId, timestamp, meta_* the same way
  case .failure(let error):
    print("Auth cancelled or failed: \(error)")
  }
}

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.)

Webhook payload contract:

{
  "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"
  }
}

Verifying Webhook Signatures

When signature headers are present, the JSON payload above is what gets signed — verify the signature before parsing the body, on the raw request bytes.

Letting Users Choose Their Channel

Let the person receiving the code decide where it arrives — WhatsApp, Telegram or SMS — instead of the pipeline deciding for them. Like passkeys, this layers onto the existing widget: same attempt lifecycle, same result contracts, and no change to your integration at all.

How it works

The picker only ever appears after the user has passed the standard checks — it is never the first thing they see.

1. Captcha. The user passes the Cloudflare Turnstile check, exactly as today.
2. The choice appears, in one of two shapes depending on the pipeline's mode:
   • Ask first — nothing has been sent yet, and the user is asked up front where they want the code.
   • Send first — the code goes out on the pipeline's normal channel immediately, and the other channels are offered under the OTP input, for when it has not arrived.
3. They pick, and the code is sent on that channel. From there the flow is the ordinary OTP flow.
4. Success is identical — same redirect, same signed webhook, same postMessage. Nothing about your callback handling changes.

One resend per attempt

This is the part integrators most often get wrong: an attempt allows exactly one resend in total — and choosing a different channel is that resend.

• The first send goes out on the channel the user picked (or, in send-first mode, on the pipeline's own first channel).
• They then get one more send. They may spend it on the same channel or on a different one; either way it is the same single resend.
• After that, further resends are refused with RESEND_LIMIT_EXCEEDED and the user must start a new attempt. This cap is not new and is not specific to channel choice — it is the widget's existing resend limit.

When a channel cannot be reached at all

telegram is the only channel whose reachability we can test before spending a send. If the number is not on Telegram, the user is returned to the picker with Telegram removed and their resend is not consumed — nothing was sent, so nothing was spent.

whatsapp and sms cannot be tested up front. A number with no WhatsApp is only discovered after the message is accepted by the provider and later reported undelivered, which is a delivery failure rather than a bounce — so it is handled by the settings below, not by returning the user to the picker.

When a chosen channel fails to deliver

Two settings, chosen per pipeline. Both concern a send the provider accepted and later reported as failed:

• Fallback (default) — the pipeline's normal fallback order takes over, so the user still gets their code, just not where they asked.
• Hard pin — no fallback is sent; the attempt is left to fail rather than arriving somewhere the user did not choose. Choose this when "this channel or nothing" matters more than delivery.

Billing

Each channel bills at its own rate, exactly as sending does today — a user choosing SMS costs what SMS costs on that country's rate. The feature adds no charge of its own, and a bounce that sent nothing bills nothing. Your own per-country rates are in Dashboard > Cost.

Passkeys

Let returning users verify with the biometric that already unlocks their device — Face ID, Touch ID, Windows Hello, or a screen lock — instead of waiting for an OTP. Passkeys layer directly onto the V2 Widget: same attempt lifecycle, same result contracts, one optional change to your embed.

How passkeys work

Passkeys are woven into the existing widget flow — the user is never stranded on a passkey screen.

1. Captcha. The user passes the standard Cloudflare Turnstile check, exactly as today.
2. Returning user with a passkey on this device. If the bound phone already has a passkey on this device, the widget offers an optional "Use passkey" button. "Use a code instead" is always shown alongside it.
3. Everyone else goes straight to normal OTP — no extra screens.
4. Success is identical to OTP — same redirect, same webhook contract, same postMessage. A passkey success may add verificationMethod: "passkey".
5. After an OTP success, the widget may show an optional, skippable "Enable passkey" prompt so the next verification is instant.

What to add per surface

What you change depends only on how you embed the widget. There are no new API routes, parameters, or SDK upgrades — the widget runs the passkey ceremonies itself.

allow="publickey-credentials-get *; publickey-credentials-create *"

<!-- Before -->
<iframe src="https://auth.akedly.io/auth?attemptId=..."></iframe>

<!-- After -->
<iframe
  src="https://auth.akedly.io/auth?attemptId=..."
  allow="publickey-credentials-get *; publickey-credentials-create *"
></iframe>

allow="publickey-credentials-get https://auth.akedly.io; publickey-credentials-create https://auth.akedly.io"

Enabling passkeys for your account

Passkeys appear only when all three of these are true:

Add the allow attribute now, then — once the pipeline's Passkeys setting is on (stored as pipeline.passkeyEnabled), the current production rollout is on, and the account is entitled — passkeys light up with no further code changes.

Debugging tips

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
}

V2 Widget errors reach you by four different routes, and the route decides the shape of the response body — so check which table a code is in before writing a handler for it. Shared-handler responses carry retryable and action. Endpoint-handler responses list their endpoint-specific body fields. Middleware responses carry the fields shown in their row. Dual-path codes arrive both ways depending on the endpoint.

Shared error-handler responses

Returned by the passkey SDK endpoints and by middleware that hands the error to the shared handler. These bodies carry retryable and action alongside the code.

On create-attempt, authenticateCreateAttempt runs before the controller. Its MISSING_REQUIRED_FIELDS, INVALID_SIGNATURE, SIGNATURE_EXPIRED responses use status, code, message, retryable, action.

Error-handler fallbacks

Endpoint-handler responses

The widget endpoints choose the status in the handler itself. These rows list the fields emitted by each endpoint. Some handlers add retryable or conditional redirect/quota fields.

Direct error responses (rate limits, circuit breaker, bans)

Rate-limit and circuit-breaker rows are answered by middleware, before the endpoint handler runs at all — so they pre-empt that endpoint's own rows. The zero-verify ban is different: IDENTITY_TEMPORARILY_BLOCKED is returned by the request-otp and resend-otp handlers themselves, and it is close to last in both — so an earlier error always wins over the ban.

request-otp checks, in order: required fields, attempt lookup, attempt expiry, the live test-pair/widget load, the idempotent already-requested return, captcha state, the account lookup, then the ban. The idempotent step is the one worth planning for: a repeat of a request that already succeeded returns that success, so a caller retrying after a dropped response gets the original result rather than CAPTCHA_NOT_VERIFIED.

resend-otp has no captcha step. It checks required fields, attempt lookup, whether an OTP was requested at all, the live test pair, the resend limit, the transaction lookup and its ownership, transaction expiry, then the ban.

The rows list the fields available on each response. Where present, retryAfter is an ISO timestamp and cooldownSeconds the equivalent in seconds. Wait for that schedule rather than retrying on a fixed interval.

Dual-path 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 OTP (4, 5 or 6 digits)
  },
)

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 outside the 60-second window (stale or ahead of server time)

Solutions:

• Verify you're using HMAC-SHA256
• Ensure the message format matches the attempt. A phone attempt signs JSON.stringify({ apiKey, publicKey, timestamp, phoneNumber }). An email-only attempt signs JSON.stringify({ apiKey, publicKey, timestamp }) — phoneNumber is omitted entirely, not sent as null or "", because the server builds the same string from an absent value and JSON.stringify drops an undefined property. Adding the key back is the usual cause of an email-only signature mismatch.
• Check your widget secret matches the dashboard
• Synchronize server clock with NTP — a clock 60+ seconds fast fails as hard as one that is slow
• Generate a fresh timestamp and signature per request; never queue or replay a signed payload

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 Authentication → Setup → Widgets → [Your Widget]
• Edit the widget and open the Pipeline section
• 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.2 REST API
• Passkeys Guide

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