Skip to content
Akedly
V2.0 WidgetsRECOMMENDED

V2.0 Widgets

V2.0 Widgets are a hosted verification screen you embed in an iframe. Your backend creates an attempt, Akedly runs the code flow, captcha, device checks and rate limits in the widget, and your server gets the result by redirect, postMessage and webhook. It is the recommended way to verify users with Akedly, and the shortest route to passkeys.

Build with AI agents
Note:

Billing Is Unchanged by V2.0

Choosing V2.0 Widgets does not change how you are billed. Akedly resolves your billing mode — pay-per-message (charged when the OTP is sent) or pay-per-success (charged on successful verification) — from your account's plan and billing mode. Neither mode is gated on the API version or on using a widget. The one per-request override is supplying your own otp, which forces pay-per-message for that transaction.

Note:

New: Passkeys for V2 Widgets

Your users can now verify instantly with a device passkey (Face ID, Touch ID, Windows Hello) instead of waiting for a code — pricing depends on your account's passkey configuration (by default 60% of your own OTP price for that phone number). It's recommended and fully backward-compatible: do nothing and you keep OTP. To enable it, add one attribute to your iframe — allow="publickey-credentials-get *; publickey-credentials-create *". Read the passkeys guide →

Why Choose V2.0 Widgets

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.

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

When to choose V2.0

  • You want Akedly to run the verification screen, with your logo and colors.
  • You want the widest security tier, including a managed iframe defense layer and device identity.
  • You want passkeys with one iframe attribute.
  • You are a qualifying startup looking at pay-per-successful-authentication pricing (requirements apply).

Choose V1.2 instead if you cannot embed an iframe or open a system browser. In a native app the widget must open in a system browser, not a WebView.

Page map

  1. Set up the widget: create it in the dashboard.
  2. Create an attempt: sign and create it from your backend.
  3. Open the widget: iframe, mobile, cookie handling and the browser-side result.
  4. Results and callbacks: the webhook payload your backend receives.
  5. Channels and security: channel choice and security features.
  6. Errors and troubleshooting: error codes, your own OTP and common fixes.

Next: after the first successful verification, turn on passkeys so the next sign-in is a biometric or screen lock. OTP once, Passkey forever.

How V2.0 Widgets Work

The authentication flow is simple and secure:

  1. Your User Initiates Authentication

    User clicks "Login" or "Verify Phone" in your application.

  2. Your Backend Creates Attempt

    Your backend calls Akedly API with HMAC signature:

    POST /api/v1/widget-sdk/create-attempt

  3. Akedly Returns Transaction URL

    Response includes:

    • Name
      attemptId
      Type
      string
      Description

      Unique attempt identifier

    • Name
      iframeUrl
      Type
      string
      Description

      URL to open in iframe for authentication

    • Name
      expiresAt
      Type
      string
      Description

      ISO 8601 timestamp when attempt expires

  4. Your Frontend Opens Widget

    Display the widget in an iframe (web), or open it in a system browser (mobile native — see Step 3):

    <iframe src={iframeUrl} />

  5. Your User Completes Authentication

    Inside the widget (managed by Akedly):

    • Device fingerprinting and security checks
    • Bot protection
    • Rate limiting
    • Fraud detection
    • OTP delivery (WhatsApp → Telegram → SMS → Email) (depending on your pipeline setup)
    • User enters OTP code

  6. Receive Verification Result

    Akedly redirects user to your callback URL & sends webhook to your backend with verification status.

Tip:

The entire authentication process (captcha, OTP, verification) is handled inside the widget. You only need to create the attempt and handle the success callback.

Support & Resources

Getting Help

Additional Resources

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