Skip to content
Akedly
Gateway

Set up the gateway

Create a gateway integration in the dashboard, then set its screens' branding, callbacks, bot checks, rate limits and circuit breaker.

Step 1: Create a gateway integration

Before integrating, create a gateway integration in your Akedly dashboard. It comes with its first gateway screen.

  1. Log in to your Akedly dashboard at https://app.akedly.io.
  2. Open Integrations in the sidebar and select New integration.
  3. Choose Verify users, then Gateway (recommended).
  4. 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.
  5. Choose the delivery channels and, optionally, the integration's Home countries, which help Cluster Gate block abuse from unexpected countries.
  6. On Keys, copy the screen's Gateway public key and Gateway secret. The secret is shown only here.
  7. 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.

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.

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:

text
https://yourapp.com/auth/callback

Success Redirect:

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

Failure Redirect:

text
https://yourapp.com/auth/callback?status=failed&error=INVALID_OTP&transactionId=mtx_abc123&attemptId=attempt_xyz789&timestamp=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:

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

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.

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 retryAfter and cooldownSeconds fields in the 429 response, which are measured from the oldest counted attempt in the window that was breached.

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.

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, widgetId in 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