Integrations
An integration holds everything Akedly needs to verify your users: its type, its channels, its protections and where results go.
Formerly Pipeline Setup
Integrations used to be called pipelines, and this page lived at /pipelines. Old links still work. The API is unchanged: the Integration ID is still sent as pipelineID, and the API paths and field names keep their names.
Managed Vodafone integrations differ
BYO SMS here describes an integration you build and own. If Akedly operates a managed Vodafone integration for your account, several of the capabilities described below are fixed by Akedly and are not yours to set — see Managed Vodafone.
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.
| Type | Who builds the screens | Guide |
|---|---|---|
| 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 |
| Headless | You 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 |
| Legacy | The 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.
The type is fixed
The dashboard never changes an integration's type. To move a headless integration to Gateway, upgrade it to V2.0 (below): that creates a new gateway integration. To move any other way, create a new integration of the other type and shift your traffic to it. A headless integration cannot have gateway screens; the API refuses to attach one.
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
pipelineIDin 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:
Type.
Choose Verify users or Send messages (One-way messaging), then, for verification, Gateway or Headless.
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.
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.
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.
Building with agents?
Let Claude Code, Codex or another coding agent build this integration end to end in about 2 minutes, with our agent skill and CLI. Start at AI agents and LLMs or the CLI guide.
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.
| Control | Effect |
|---|---|
| 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.
Rate-limit and breaker bypass is scoped to the test number
Only traffic matching the test pair skips those two controls; every other request to the integration stays fully rate-limited and breaker-protected for the whole hour. Skip proof-of-work and Skip Cloudflare check are the exception: they apply to the whole integration while the window is open. Do not leave developer mode on for an integration serving real traffic.
Channels
Which channels deliver the code, and in which order.
Delivery order
| Control | Effect |
|---|---|
| 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
- 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
- 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'sotpLanguageoverrides 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.
Optional for headless integrations
On a headless integration the webhook URL is optional: you already receive the verification result in the API response. Set it if you also want an out-of-band record of each result. A gateway integration can be tested without them, but needs both the Return URL and the Server URL (both on Webhooks) before it goes Live.
| Control | Effect |
|---|---|
| Server URLstring | Under Where we send results. The URL ( |
| Return URLstring | Gateway only, under Where we send users. Where we send people back after they verify ( |
| Verification resultalways on | Always on. It cannot be turned off independently of the URL. |
| Channels resolvedswitch | Sends |
| Channels updatedswitch | Sends |
| Delivery receiptsswitch | Sends |
| 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.
Legacy verification-result callbacks are NOT signed
On a legacy (V1.0) integration, the verification-result callback arrives unsigned: no svix-id, svix-timestamp or svix-signature headers. A handler that rejects unsigned requests will drop every legitimate legacy result. Verify it by looking up the transactionID from the payload against your own record of the transaction you started, and treat the URL itself as non-secret. On headless the verification result is signed with the webhook signing secret (best effort; confirm through the API if one ever arrives unsigned). OTP channel events and delivery receipts are always signed.
Where the webhook signing secret is used
The integration's whsec_ secret signs gateway webhooks, headless verification results, OTP channel events and delivery receipts, and One-way messaging webhooks. The legacy verification-result callback stays unsigned. For headless passkeys, the ceremony's resultToken is an additional signed proof, which you verify offline; see Passkeys on Headless. See the webhook signing guide.
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
- Gateway: follow Set up the gateway, then Create an attempt.
- Headless: call the API with your API key and the Integration ID; start at Set up the integration.
- Legacy: plan the move with Migrate from Legacy.
