Set up the gateway
Create a gateway integration in the dashboard, then set its screens' branding, callbacks, bot checks, rate limits and circuit breaker.
Formerly V2.0 Widgets
Gateway was called V2.0 Widgets, and gateway screens were called widgets. This page was at /authentication/v2/setup; old links still work. The API and its field names are unchanged.
Step 1: Create a gateway integration
Before integrating, create a gateway integration in your Akedly dashboard. It comes with its first gateway screen.
- Log in to your Akedly dashboard at https://app.akedly.io.
- Open Integrations in the sidebar and select New integration.
- Choose Verify users, then Gateway (recommended).
- Name the integration. Where to send users after they verify (the return URL) and your webhook URL (the server URL) are set later on the integration's Webhooks tab. You can test without them; a gateway needs both before it goes Live.
- Choose the delivery channels and, optionally, the integration's Home countries, which help Cluster Gate block abuse from unexpected countries.
- On Keys, copy the screen's Gateway public key and Gateway secret. The secret is shown only here.
- The new integration starts on, in Test mode, so you can test right away. To go Live, add the Return URL and Server URL on the Webhooks tab, then switch Mode to Live on the Basics tab.
To add another screen to the same integration, open the integration's Gateway screens tab and add one. Every screen shares the integration's channels and webhooks, and has its own look, language, bot checks, rate limits and keys.
Where gateway screens are created
Create gateway integrations and screens in the dashboard, or with the Akedly CLI (akedly integrations create --type gateway, akedly integrations screens create). They cannot be created with an API key.
Screen details
Open a screen from the Gateway screens tab to edit it.
- Name
- Name
- Type
- string
- Description
Internal name for your reference, for example "Production login". Up to 100 characters.
- Name
- Description
- Type
- string
- Description
Optional note on where the screen is used. Up to 500 characters.
- Name
- Integration
- Type
- string
- Description
The gateway integration the screen belongs to. Moving it changes where its codes and results go.
The screen's bot checks, rate limits and circuit breaker are on the integration's Security tab, under Screen protection; with several screens, pick one there. The sections below describe each setting.
Branding
The integration's Branding tab shows a live preview of one screen (a picker when there are several). Open studio opens the Branding Studio for that screen, which has a live preview beside a rail of eight sections, ordered from the whole page down to single elements.
- Name
- Themes
- Type
- section
- Description
Start from a ready-made look. Your logo, name, wording, language and header are kept.
- Name
- Brand
- Type
- section
- Description
Your logo, company name and browser-tab icon.
- Name
- Colors
- Type
- section
- Description
Light or dark mode, the primary, secondary and accent colors, page and text colors, and the page backdrop (solid, gradient, dots or grid). Palettes set the three brand colors in one click.
- Name
- Shape
- Type
- section
- Description
Corners, depth and spacing across the gateway screen.
- Name
- Typography
- Type
- section
- Description
Font, an optional separate heading font, text size and weights.
- Name
- Layout
- Type
- section
- Description
How the page is arranged — Centered, Split (brand left or right) or Compact — plus logo position and alignment.
- Name
- Elements
- Type
- section
- Description
Fine-tune single parts — Card, Buttons, Channel buttons, Code boxes, Links, Header, Success screen and Error screen. Settings left on Auto follow the sections above.
- Name
- Text
- Type
- section
- Description
Language and wording. Leave a field empty to keep the default text.
The Themes section offers twelve ready-made Themes — Akedly, Midnight, Minimal, Corporate, Playful, Ledger, Aurora, Lapis, Graphite, Sunrise, Editorial and Calm. Rest the pointer on one to try it on the preview; click it to apply it, and use Undo to go back. Applying a Theme copies its values into your draft, so you can keep editing; the Theme card shows Customized once you have.
The preview beside the rail is live and renders the real gateway screen: loading, OTP entry, success and error, plus the captcha, passkey and channel screens when those are enabled on the gateway screen. Toggle Show inactive screens to include the screens your gateway screen does not currently use, and switch the preview between desktop, tablet and mobile — each renders at that device's real width. Focus a setting to outline the part of the gateway screen it changes; turn on Inspect and click a part of the preview to jump to its settings.
Edits are not applied until you press Save changes; Discard returns to the last saved branding.
Branding is set per gateway screen, so a screen must exist before you can open its Branding Studio. Open it from the Branding tab, or from the Look card on the screen's page.
Webhooks
Gateway supports two types of callbacks, both on the integration's Webhooks tab: the Return URL under Where we send users, and the Server URL under Where we send results. You can test without them; both are needed before the integration goes Live. See Integrations.
Return URL (needed before Live)
Where to redirect the user after authentication completes.
Example:
https://yourapp.com/auth/callback
Success Redirect:
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
Failure Redirect:
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
A request-otp call whose first send could not be confirmed (OTP_DISPATCH_OUTCOME_UNKNOWN) can also return this failure redirect in its error body. That path sends no backend webhook. See the Error Reference (OTP dispatch responses).
Server URL (needed before Live)
Webhook endpoint for verification results. The same URL receives selected signed OTP channel events and Delivery receipts. gateway integrations you create in the dashboard or through the API start with these events on; other gateway integrations, including existing ones, start with them off. Route envelopes by eventType before handling the unchanged verification result.
Example:
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 withmeta_. Object values are JSON stringified.
Bot checks
Protect your gateway screen from automated attacks with built-in captcha verification.
- Name
- Enable Captcha
- Type
- boolean
- Description
Always enabled by default. Captcha verification is mandatory for all gateway screen interactions and cannot be disabled.
- Name
- Require Cloudflare Turnstile
- Type
- boolean
- Description
Always enabled. Cloudflare Turnstile is required to protect your quotas and gateway screens 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 gateway screen from abuse. Rate limits are configured across three dimensions: per phone number, per device ID (fingerprinting), and per gateway screen.
The Rate limits card shows the hourly code limits per phone number, per device and for the screen. Edit all limits opens every limit, for codes sent and screen opens, and the Wait after a limit. Done puts your changes on the page; Save applies them.
Suggested limits: with enough traffic history, open Edit all limits, pick a period under Suggest limits from and select Suggest. Use these fills every limit from your busiest times in that period, within the caps below.
Default values suit most integrations. Change them only for a real need. Nothing is recalculated for you: when you raise a screen's per-minute limit, raise its per-hour and per-day limits too, in Edit all limits. The hourly limit must be at least 5 times the minute limit and the daily limit at least 100 times, or the change cannot be saved. For example, a per-minute limit of 30 needs at least 150 an hour and 3000 a day.
Screen attempts
Screen 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.
OTP Requests
OTP requests track actual One-Time Password deliveries. These limits apply only when an OTP is successfully sent to the user.
Cooldown Duration
- Name
- Cooldown duration
- Type
- number
- Description
Default: 300000 (5 minutes). Stored on the gateway screen, but the Gateway rate limiter does not read it. When a Gateway request is rate limited, the wait comes from the
retryAfterandcooldownSecondsfields in the 429 response, which are measured from the oldest counted attempt in the window that was breached.
No implicit per-request cooldown on Gateway
The platform-wide 60-second cooldown between OTP requests does not apply to gateway screen requests — this endpoint skips it deliberately, because the gateway screen's own per-phone and per-device limits above already govern the pace. These limits REPLACE that cooldown; they are not the only guard a gateway integration meets. The resend limit always applies. Zero-verify bans apply on top only when BOTH are true: Akedly has enforcement switched on platform-wide (it is off by default, and its shadow setting records what it would have blocked without returning a refusal), AND the integration has not disabled them. Live test-pair attempts are exempt, so a request using the test pair's number will never show you a ban — check ban handling with any other number, which is treated normally even while dev mode is on. Treat a ban response as something to handle if it arrives, never as protection you can assume is active.
Circuit Breaker
The circuit breaker is your final layer of defense that automatically suspends your gateway screen when abnormal traffic patterns are detected. It works alongside captcha and rate limiting to provide comprehensive protection.
Keep Circuit Breaker Enabled. Disabling the circuit breaker removes your last line of defense against sophisticated attacks. The circuit breaker is calibrated to only trigger during genuine flood attacks—if it activates, it means it protected you from a real threat.
Why Circuit Breaker Matters:
- Blocks Coordinated DDoS Attacks: Detects and stops distributed attacks from multiple sources attempting to overwhelm your gateway screen
- 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 gateway screen during attacks and automatically resumes normal operation when the threat subsides
After you create a screen
Once you create the gateway screen, you'll receive credentials needed for API integration:
- Name
- Gateway screen ID
- Type
- string
- Description
Internal identifier,
widgetIdin the API (e.g.,widget_a1b2c3d4...)
- Name
- Gateway public key
- Type
- string
- Description
Used in API requests (e.g.,
pk_x1y2z3...)
- Name
- Gateway secret (save it now)
- Type
- string
- Description
Used to sign API requests with HMAC-SHA256
The secret is shown once and cannot be rotated
The gateway secret is displayed only at creation — copy it then, as shown in the screenshot. There is no regenerate or rotate action for a gateway screen secret anywhere in the product, so losing it is not self-service recoverable: you would have to create a new gateway screen (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.
