Skip to content
Akedly
Start

Integrations

An integration holds everything Akedly needs to verify your users: its type, its channels, its protections and where results go.

Every OTP request runs against one integration. It decides which channels deliver the code and in which order, which protections apply, and where Akedly sends the result. Open Integrations in the dashboard to see them all, and select one to open its page.


Integration types

An integration has one type, chosen when you create it. The type decides how your app talks to Akedly and which tabs the integration page shows.

TypeWho builds the screensGuide
Gateway (recommended)We host the screens and you brand them. Your app opens a gateway screen and your server reads the signed result. Bot checks, rate limits, AI protection and passkeys are built in. Formerly V2.0 Widgets (API version v2).Gateway
HeadlessYou build every screen in your app and call our API to send and check each code. Bot checks, rate limits, AI protection and passkeys run through the API. Formerly the V1.2 REST API (API version v1.2).Headless
LegacyThe V1.0 REST API. It sunsets on December 30, 2026; move to Gateway or Headless.Legacy REST API (V1.0)

Start with Gateway. It is the recommended type and needs the least code. Choose Headless when you want to build the screens yourself, or when your app cannot open a gateway screen in an iframe or a system browser.

A One-way messaging (Utilities) integration sends order updates, reminders and alerts rather than codes. It is listed on the same page; its setup is in One-way messaging.

Upgrade a headless integration to V2.0

A headless integration (V1.2) can be upgraded to Gateway (V2.0) in one step. Select Upgrade to V2.0 in the More actions menu at the top of the integration, or in the Want us to host the sign-in? card on its Basics tab. The confirmation lists what is copied and warns Your keys will change; select Upgrade.

  • A new integration. The upgrade creates a new gateway integration with the same name, its own Integration ID, a new Webhook signing secret and a default gateway screen with a new Gateway public key and Gateway secret. The secrets are shown once, in Save your new keys. The new integration starts on, and it is Live only when the old one was Live with both a Return URL and a Server URL.
  • What is copied. The channels, their order and channel choice; the code message language, or your custom code message; Smart routing and blocked numbers; destination and home countries; passkeys; the Return URL, Server URL and webhook events. Bot checks and the passkey page's look are not copied. The new gateway screen starts with standard gateway limits, not the old integration's rate limits; change them on the new integration's Security tab.
  • The old integration keeps working with its old keys until you delete it, so your app keeps running while you switch it to the new keys. It then shows Looks like you've upgraded to V2.0 (Hosted gateway) of our APIs. Would you like to delete this old integration to clean up? with Delete. Deleting it hides it from your account and stops its keys at once; its verification history, analytics and billing stay under its name. Gateway screens already attached to it stay with it and stop working when you delete it.
  • When it is refused. Nothing is created when the integration sends SMS through its own SMS provider added only to it (remove that provider under Providers on this integration on the Channels tab, upgrade, then add it to the new integration with Add from your providers and send a test), or when it uses a custom code message and your role can't set code messages. An integration can be upgraded once.

With the CLI, follow Upgrade a headless integration to the gateway.


Names you will see

  • Name
    Integration ID
    Description

    The integration's identifier. Your server sends it as pipelineID in API calls.

  • Name
    Gateway screen
    Description

    The hosted screen your users verify on. A gateway integration holds one or more gateway screens; the integration's settings are shared by all of them, and each screen has its own look, language, bot checks, rate limits and keys. Gateway screens were called widgets, and the API still calls them that (widgetId).

  • Name
    Gateway public key
    Description

    Identifies one gateway screen when your server creates an attempt. One per screen.

  • Name
    Gateway secret
    Description

    Signs your server's requests for one gateway screen. Shown once, when the screen is created.

  • Name
    Webhook signing secret
    Description

    The integration's whsec_ secret. Akedly signs webhook deliveries with it.


Create an integration

Select New integration on the Integrations page. The steps are:

  1. Type.

    Choose Verify users or Send messages (One-way messaging), then, for verification, Gateway or Headless.

  2. Basics.

    Name the integration. A gateway integration also names its first gateway screen (optional). Where to send users and your server URL are set later, on the Webhooks tab.

  3. Channels.

    Choose how codes are delivered. You can change this later on the Channels tab. On Gateway and Headless, where Cluster Gate is available, you can also set the integration's Home countries: optional, filled in from your countries on the Rates page. They help Cluster Gate block abuse from unexpected countries and show your prices; change them later on the Security tab.

  4. Keys.

    Copy the keys your server needs. A gateway screen's Gateway secret is shown only here.

A new integration starts on, in Test mode. When it is ready, switch Mode to Live on its Basics tab; a gateway integration needs its Return URL and Server URL first. To stop every code, tests included, select Turn off in the More actions menu at the top of the integration.


Basics

The first tab. It shows a setup checklist, the keys your server needs, and today's numbers, including codes sent each hour since midnight. The Integration ID is in the page header, under the integration's name, with a copy button; it is also in the More actions menu as Copy ID. For the last 24 hours hour by hour, open Activity and choose 24 hours.

ControlEffect
Setupchecklist

What is still missing, such as the Server URL and Return URL a gateway integration needs before it goes Live, or an integration that was turned off. Check it first when a call fails.

Keys and IDsread-only

On a gateway integration, each screen's Gateway public key; the Webhook signing secret; and a link to your account's API keys. The Integration ID is not here: copy it from under the integration's name at the top of the page.

Detailsstring

The integration's name and description. On a headless integration, also After verifying, send users to: the address users return to after a hosted passkey flow. A gateway integration sets this address on the Webhooks tab.

Live and testingtoggle

Mode: Live or Test. Both send real codes, the same way; Test marks an integration you're still building. A gateway integration can't switch to Live until its Return URL and Server URL are set.

Developer mode

Select Developer mode in the integration's header, beside Test now, then Start developer mode. It mints a test phone-and-code pair and holds it for one hour; while it runs, a band at the top of every dashboard page shows the test number and code. Requests for that number skip rate limiting and the circuit breaker, so you can iterate without tripping the integration's own protections. On a headless integration it also offers Skip proof-of-work and Skip Cloudflare check. On a gateway integration it runs on a gateway screen; pick the screen in the popover. See Dev Mode & Test Pairs.


Channels

Which channels deliver the code, and in which order.

Delivery order

ControlEffect
Let Akedly choose (recommended)option

Needs at least two channels. The first attempt is WhatsApp, even when WhatsApp is not one of the channels you added, unless Smart routing skips it or the user picks a channel with Let users choose the channel (both below). If it fails, Akedly falls back to Telegram, then SMS, using only the channels you added. If an integration must never send over WhatsApp, choose Use my order instead.

Use my orderoption

Tried top to bottom. SMS can go anywhere in the list, including first, and the order is honoured.

Add channelbutton

WhatsApp, Telegram, SMS or email. When the API request supplies an email address, the code also goes by email, once, with the first phone attempt.

  • Name
    WhatsApp
    Description

    Sent from Akedly's shared number by default. Connect your own Business Account to send from your brand number and reach nine more destinations.

  • Name
    Telegram
    Description

    Telegram's official OTP verification channel.

  • Name
    SMS
    Description

    Sent by Akedly, or by your own SMS provider.

  • Name
    Email
    Description

    Used when the request carries an email address: the code goes by email once, together with the first phone attempt, not as a fallback step.

Smart routing, channel choice and the code message

  • Smart routing skips WhatsApp for a new request when an earlier WhatsApp code to the same number has not arrived, and uses the next channel in your delivery order.
  • Let users choose the channel lets the user pick the channel. A gateway screen asks the user; on headless, your app sends the user's pick with each request; legacy requests always use your delivery order. See channel choice on Gateway and Headless.
  • Code message sets the default language of WhatsApp and SMS messages, and the WhatsApp template used when a request sends no template. A request's otpLanguage overrides the language for that request. See Set an integration default and Add a missing language.

Your own SMS provider

Route this integration's SMS through your own SMS provider instead of Akedly's senders. The setting is on, off, or the Account default, and it appears only for accounts entitled to it. Providers on this integration lists your providers; a provider cloned onto this integration is used before your account-level ones, so one integration can override the account default for a country. This card is on Gateway, Headless and Legacy integrations only; a One-way messaging integration has an SMS switch instead and is set with the CLI. See Enable on integrations & cloning.


Security

How this integration's traffic is protected. Which cards appear depends on the type.

  • Name
    Cluster Gate
    Description

    AI protection that refuses attack requests before a code is sent. Shown where it is available. See Cluster Gate AI Protection.

  • Name
    Destination countries
    Description

    Shown on every type, but it limits different things. On Gateway, Headless and Legacy integrations it limits which countries' phone numbers can receive a code: All countries, Only selected countries or All except selected countries. A code request to any other country is refused with DESTINATION_COUNTRY_BLOCKED, which limits the damage a leaked API key can do. Numbers with an unknown country are refused, and email is not limited. On a One-way messaging integration the list limits WhatsApp only: numbers outside it go by SMS if SMS is on, and one-way SMS reaches whatever countries your own SMS provider covers. To stop one-way SMS to a country, remove that country from your provider's coverage or turn SMS off.

  • Name
    Block repeat requests
    Description

    Blocks numbers that ask for codes and never use them. A block lasts 7 days, and up to 90 if it happens again. Blocked numbers are shared by all your integrations. The switch alone does not block anything: requests are refused only while Akedly also has this protection enforced platform-wide, which is off by default. Treat a block as something to handle if it arrives, never as protection you can count on.

  • Name
    Bot checks
    Description

    Headless only. Proof of work makes each request pay a small computational cost before a code is sent; it is always on, and Automatic scaling under attack (on by default) raises the level when traffic nears your rate limits. Turn it off to hold one fixed level. Cloudflare Turnstile is optional, at no extra cost.

  • Name
    Rate limits
    Description

    Headless only. Caps requests per phone number, per IP address and per integration. Set them to your real traffic, not with headroom an attacker can use.

  • Name
    Circuit breaker
    Description

    Headless only. Suspends the integration when traffic exceeds a set multiple of the rate limits, before a spike or an abuse burst drains your balance.

  • Name
    Passkeys
    Description

    Headless and gateway. Lets returning users verify with a device passkey instead of a code. If your account is not enabled for passkeys, the switch is greyed out with a request-access prompt. See Passkeys.

  • Name
    Screen protection
    Description

    Gateway only. Bot checks, rate limits and the circuit breaker are set for each gateway screen; with several screens, pick one in the card.


Gateway screens and Branding

Gateway integrations only. Gateway screens lists the screens on this integration and adds new ones; open a screen for its details, its look, its Gateway public key and its developer mode. Its bot checks, rate limits and circuit breaker are on the Security tab. Branding shows a live preview of one screen (a picker when there are several) and opens the branding studio. Setup is in Set up the gateway.


Webhooks

Where Akedly sends each verification result, and which other events it sends there.

ControlEffect
Server URLstring

Under Where we send results. The URL (backendCallbackURL) for verification results and selected OTP events, for example https://yourapp.com/api/webhooks/akedly. A gateway integration needs it before it goes Live.

Return URLstring

Gateway only, under Where we send users. Where we send people back after they verify (frontendCallbackURL). Needed before going Live.

Verification resultalways on

Always on. It cannot be turned off independently of the URL.

Channels resolvedswitch

Sends otp.channels.resolved after activation's channel wait.

Channels updatedswitch

Sends otp.channels.updated after a late WhatsApp failure settles the fallback decision.

Delivery receiptsswitch

Sends otp.message.status for WhatsApp and for SMS that Akedly sends to Egyptian numbers: sent, delivered or final failure.

Test server URLbutton

Under Test your server URL. Sends a sample result and shows your server's reply.

OTP integrations you create in the dashboard or through the API start with all three optional events on. Integrations that existed before these switches, and integrations Akedly creates for you (such as the Sandbox demo integrations), use their type's defaults: channel events on for headless and eligible legacy requests, off for gateway, and receipts off. Legacy optional events also require waitForChannels: true per request. Switching an event off stops new events; queued retries continue. Turning it back on does not replay skipped events.

See OTP channel events for routing, signatures, timing, payloads, retries and duplicate handling.


Activity

Gateway, headless and legacy integrations. Codes sent, confirmed codes and the user confirmation rate for a range you choose, split by channel, with the codes that were not confirmed. On a gateway integration you can filter by screen.


Next steps