Gateway
A gateway integration gives you a hosted verification screen, the gateway screen, that you embed in an iframe. Your backend creates an attempt, Akedly runs the code flow, captcha, device checks and rate limits in the gateway screen, 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.
Formerly V2.0 Widgets
Gateway was called V2.0 Widgets, and its pages lived under /authentication/v2. Old links still work. Gateway screens were called widgets. The API is unchanged: it is still API version v2, under /api/v1/widget-sdk, with the same field names (widgetId, pipelineID).
Billing Is Unchanged by Gateway
Choosing Gateway 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
gateway screen. The one per-request override is supplying your own otp, which forces
pay-per-message for that transaction.
New: Passkeys on gateway screens
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 Gateway
Gateway 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 Headless, Gateway, and V1.0, see the Authentication Methods overview.
When to choose Gateway
- 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 Headless instead if you cannot embed an iframe or open a system browser. In a native app the gateway screen must open in a system browser, not a WebView.
Page map
- Set up the gateway screen: create it in the dashboard.
- Create an attempt: sign and create it from your backend.
- Open the gateway screen: iframe, mobile, cookie handling and the browser-side result.
- Results and callbacks: the webhook payload your backend receives.
- Channels and security: channel choice and security features.
- 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 Gateway works
The authentication flow is simple and secure:
Your User Initiates Authentication
User clicks "Login" or "Verify Phone" in your application.
Your Backend Creates Attempt
Your backend calls Akedly API with HMAC signature:
POST /api/v1/widget-sdk/create-attemptAkedly 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
Your Frontend Opens Gateway screen
Display the gateway screen in an iframe (web), or open it in a system browser (mobile native — see Step 3):
<iframe src={iframeUrl} />Your User Completes Authentication
Inside the gateway screen (managed by Akedly):
- Device fingerprinting and security checks
- Bot protection
- Rate limiting
- Fraud detection
- OTP delivery (WhatsApp → Telegram → SMS → Email) (depending on your integration setup)
- User enters OTP code
Receive Verification Result
Akedly redirects user to your callback URL & sends webhook to your backend with verification status. The same backend URL receives selected signed channel events and Delivery receipts, with
data.attemptIdlinking them to the gateway screen attempt.
The entire authentication process (captcha, OTP, verification) is handled inside the gateway screen. You only need to create the attempt and handle the success callback.
Support & Resources
Getting Help
- Dashboard: https://app.akedly.io
- Support: support@akedly.io
- Co-founders: muhad@akedly.io, hana@akedly.io
Additional Resources
Version: 2.0.0
Last Updated: October 8th, 2026
API Base URL: https://api.akedly.io/api/v1/widget-sdk
