# Akedly

> Akedly delivers one-time passcodes by WhatsApp, Telegram, SMS and email, adds passkeys so returning users skip the code, and sends one-way utility messages. These pages are the API contract.

Integrating an application? Pick one method:

- Hosted widget (iframe), maximum security, no UI work: [V2.0 Widgets](https://docs.akedly.io/authentication/v2.md)
- Your own UI, plain REST: [V1.2 REST API](https://docs.akedly.io/authentication/v1-2.md)
- Passkeys are a capability inside either method, not a third method: [Passkeys overview](https://docs.akedly.io/authentication/passkeys.md), [Passkeys on V2.0](https://docs.akedly.io/authentication/v2/passkeys.md), [Passkeys on V1.2](https://docs.akedly.io/authentication/v1-2/passkeys.md)
- Sending one-way messages such as order confirmations, shipping updates and reminders: [Utilities](https://docs.akedly.io/utilities.md)

Rules that hold for every method:

- The API key, the pipeline ID and the widget secret are server-only. Never ship them to a browser or a mobile app.
- Branch on the error `code`, never on `message`. For a code you do not know, fall back to the HTTP status.
- Verify the signature of every signed webhook on the raw request body before trusting it. A result that arrives unsigned is confirmed with a status lookup, not trusted or rejected blindly.

Every page in one file: https://docs.akedly.io/llms-full.txt (large). Error catalogue: https://docs.akedly.io/errors.json. Agent skill: https://docs.akedly.io/agents

Docs version: 9f89a41f8375

## Get started: Basics

- [The open router for two-factor authentication](https://docs.akedly.io/index.md): One API that routes each verification over WhatsApp, Telegram, SMS and email with automatic fallback, then moves returning users to passkeys.
- [Quickstart](https://docs.akedly.io/quickstart.md): This guide will get you all set up and ready to use the Akedly API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.
- [AI agents and LLMs](https://docs.akedly.io/agents.md): Machine-readable docs for coding agents and an installable Akedly integration skill that helps an agent build V2.0 Widget, V1.2 and Utilities integrations.

## Get started: Tutorials

- [Tutorials](https://docs.akedly.io/tutorials.md): Short, task-shaped walkthroughs: drop the V2 widget into a page, send your first OTP, send a utility message, and receive a webhook.
- [Add the V2 widget](https://docs.akedly.io/tutorials/add-the-widget.md): Create a V2 pipeline, attach a widget, and drop the hosted verification flow into a page without building any UI.
- [Send your first OTP](https://docs.akedly.io/tutorials/first-otp.md): Create a V1.2 pipeline and run the three-endpoint flow — challenge, send, verify — to deliver and check a one-time code.
- [Send a utility message](https://docs.akedly.io/tutorials/first-utility-message.md): Connect a channel, create a utility pipeline, get a template approved, and send your first utility message.
- [Receive a webhook](https://docs.akedly.io/tutorials/receive-a-webhook.md): Stand up an endpoint, point a pipeline at it, verify the signature against the raw body, and watch a real delivery arrive.

## Get started: Errors

- [Errors](https://docs.akedly.io/errors.md): How Akedly reports failures: the response envelope, why you branch on `code` and never on `message`, and the one case where a non-delivery is not an error at all.

## Authentication: Start

- [Authentication Methods](https://docs.akedly.io/authentication.md): Choose between the V2.0 Widget (recommended), the V1.2 REST API, and the legacy V1.0 REST API. Compare what you build, who each is best for, and how passkeys work on each.
- [Pipeline Setup](https://docs.akedly.io/pipelines.md): Configure OTP delivery pipelines for your Akedly widgets.

## Authentication: V2.0 Widgets

- [V2.0 Widgets](https://docs.akedly.io/authentication/v2.md): RECOMMENDED: Complete guide to implementing Akedly V2.0 Widgets. Iframe-based authentication with Cloudflare Turnstile, device fingerprinting, rate limiting, and circuit breaker protection.
- [Set up the widget](https://docs.akedly.io/authentication/v2/setup.md): Create a V2.0 widget in the Akedly dashboard and configure its form, branding, callbacks, captcha, rate limits and circuit breaker.
- [Create an attempt](https://docs.akedly.io/authentication/v2/start.md): Sign a request on your backend and create a V2.0 widget attempt, with examples in popular backend languages.
- [Open the widget](https://docs.akedly.io/authentication/v2/client.md): Open the V2.0 widget in an iframe on the web or in a system browser on mobile, and handle blocked cookies.
- [Results and callbacks](https://docs.akedly.io/authentication/v2/results.md): Read the V2.0 widget backend webhook payload and verify its signature.
- [Channels and security](https://docs.akedly.io/authentication/v2/channels-and-security.md): How users choose their delivery channel in the V2.0 widget, and the security features the widget runs.
- [Errors and troubleshooting](https://docs.akedly.io/authentication/v2/errors.md): V2.0 widget error codes and dispatch responses, bring your own OTP, and fixes for common problems.

## Authentication: Passkeys

- [Passkeys](https://docs.akedly.io/authentication/passkeys.md): Verify with a code once, then with a passkey. How Akedly passkeys work, where they work, what they cost and how to turn them on for V2.0 and V1.2.
- [Passkey Network Registry](https://docs.akedly.io/authentication/passkeys/network-registry.md): A passkey saved at one Akedly app works at any other with passkeys on. How the Registry works, when a code is still asked, what it costs and what is shared.
- [Passkeys on V2.0](https://docs.akedly.io/authentication/v2/passkeys.md): Add passkeys to the V2.0 widget so returning users verify with their device instead of a code.
- [V1.2 Passkeys](https://docs.akedly.io/authentication/v1-2/passkeys.md): Integrate V1.2 passkey enrollment and authentication with Akedly Shield, including endpoint contracts, OTP fallback, result proof, and callbacks.

## Authentication: V1.2 REST API

- [V1.2 REST API](https://docs.akedly.io/authentication/v1-2.md): V1.2 REST API with Akedly Shield: configurable Proof-of-Work and Turnstile protection. Same REST simplicity as V1, no iframe required.
- [Set up the pipeline](https://docs.akedly.io/authentication/v1-2/setup.md): Where the V1.2 API key and pipeline ID come from, and the API version a V1.2 pipeline needs.
- [Get a challenge and send the OTP](https://docs.akedly.io/authentication/v1-2/start.md): Request a V1.2 challenge, send the OTP with the proofs it needs, and set the OTP message language.
- [Solve the challenge](https://docs.akedly.io/authentication/v1-2/client.md): Solve the V1.2 proof-of-work challenge and get a Turnstile token on the client, and find the Shield SDK for your platform.
- [Verify and callbacks](https://docs.akedly.io/authentication/v1-2/results.md): Verify the OTP your user entered, then read the verification-result callback your server receives.
- [Channels and security](https://docs.akedly.io/authentication/v1-2/channels-and-security.md): How users choose their delivery channel on V1.2, and how proof-of-work difficulty, challenge expiry and Turnstile work.
- [Errors and troubleshooting](https://docs.akedly.io/authentication/v1-2/errors.md): V1.2 error codes by category, with the expiry limits that apply.
- [Migrate from V1.0](https://docs.akedly.io/authentication/v1-2/migration.md): How the V1.0 transaction calls map to the V1.2 flow, with before and after code.

## Authentication: V1.2 Shield SDKs

- [Shield SDKs](https://docs.akedly.io/authentication/v1-2/sdks.md): Official Akedly Shield SDKs for Proof-of-Work solving and Turnstile captcha across Web, Flutter, iOS, Android, and React Native.
- [Web / JavaScript Shield SDK](https://docs.akedly.io/authentication/v1-2/sdks/web.md): Akedly Shield SDK for JavaScript. Proof-of-Work solver with Web Worker support and Turnstile helper for browsers, React Native, and Node.js.
- [iOS / Swift Shield SDK](https://docs.akedly.io/authentication/v1-2/sdks/ios.md): Akedly Shield SDK for iOS and macOS. Async PoW solver with CryptoKit and WKWebView-based Turnstile integration.
- [Android / Kotlin Shield SDK](https://docs.akedly.io/authentication/v1-2/sdks/android.md): Akedly Shield SDK for Android, distributed as a GitHub repository via JitPack. Coroutine-based PoW solver and invisible WebView Turnstile integration for Kotlin and Java.
- [Flutter / Dart Shield SDK](https://docs.akedly.io/authentication/v1-2/sdks/flutter.md): Akedly Shield SDK for Flutter and Dart, distributed as a GitHub repository. PoW solver with Isolate support and Turnstile widget for mobile and web platforms.
- [React Native Shield SDK](https://docs.akedly.io/authentication/v1-2/sdks/react-native.md): Akedly Shield for React Native. Uses @akedly/shield npm package with batched main-thread PoW and bridge page Turnstile.

## Authentication: Cluster Gate AI Protection

- [Cluster Gate AI Protection](https://docs.akedly.io/authentication/cluster-gate.md): COMING SOON: An AI-powered protection layer for V1.2 and the V2.0 Widget, coming soon. Availability may vary by region.

## Authentication: TOTP

- [TOTP Authentication](https://docs.akedly.io/totp-authentication.md): TOTP (authenticator-app codes) is superseded by passkeys. This page covers TOTP for existing pipelines.

## Authentication: Testing & going live

- [Dev Mode & Test Pairs](https://docs.akedly.io/authentication/dev-mode.md): Test your Akedly integration end to end without sending a single message. Dev mode mints a temporary phone-and-OTP test pair — with a selectable OTP length of 4, 5 or 6 digits — that verifies successfully while skipping provider delivery, billing, rate limiting and delivery-status forwarding while preserving your callback.
- [Webhooks](https://docs.akedly.io/webhooks.md): What Akedly sends to your server, how to receive it, and how to check it really came from us. Start here if you have never handled a webhook before.
- [Transaction status lookup](https://docs.akedly.io/authentication/transaction-status.md): Ask Akedly for the current result of a verification by transactionID or attemptId, one at a time or up to 50 per call. Use it when a webhook is late, missing or unsigned.

## Utilities: Utilities

- [Utilities](https://docs.akedly.io/utilities.md): Send one-way transactional messages — order confirmations, shipping updates — from your backend over WhatsApp (your own Business Account) and SMS (your own BYO provider).
- [Send API](https://docs.akedly.io/utilities/send.md): POST /api/v1/utilities/send reference: request signing headers, template and free-text modes, channel resolution, response shapes, and the errors you are most likely to meet. Code lists here are not exhaustive.
- [Utility Webhooks](https://docs.akedly.io/utilities/webhooks.md): Receive delivery status, replies, button taps and Meta template approvals and rejections from your WhatsApp utility pipelines — a direct BYO-SMS leg produces no post-send events, while a WhatsApp attempt that falls back can still emit its own failed status. The event flow, a working handler, the four payloads, the one-use template details lookup, and what happens when your endpoint is down.
- [Request Signing](https://docs.akedly.io/utilities/signing.md): Sign utilities API requests with HMAC-SHA256: the x-akedly-timestamp, x-akedly-nonce, and x-akedly-signature headers, per-language helpers, and troubleshooting.
- [End Users](https://docs.akedly.io/utilities/end-users.md): Bind your internal user IDs to phone numbers and look them up later: POST /api/v1/utilities/end-users and /end-users/lookup reference.

## Channels: Overview

- [Channels](https://docs.akedly.io/channels.md): The connections your messages go out over. Bring your own WhatsApp Business Account and your own SMS provider, and see what each one unlocks for Authentication and for Utilities.

## Channels: WhatsApp

- [Your WhatsApp Business Account](https://docs.akedly.io/channels/whatsapp.md): Connect your own WABA through Meta Embedded Signup: what it unlocks for OTP and Utilities, the five setup steps, Business Verification, and what happens when you disconnect.
- [OTP templates](https://docs.akedly.io/channels/whatsapp/otp-templates.md): NEW: Send WhatsApp OTPs in Meta library wording from your own WhatsApp Business Account: add a template in the dashboard, wait for approval, then pass its id or make it a pipeline default.

## Channels: Your own SMS provider

- [Bring Your Own (BYO) SMS](https://docs.akedly.io/channels/byo-sms.md): Route OTP and utility SMS through your own provider's HTTP API while Akedly composes the message and verifies OTPs, with fees determined by the SMS use case.
- [Build an integration](https://docs.akedly.io/channels/byo-sms/setup.md): Build a BYO SMS integration in the Akedly dashboard, including coverage, secrets, request steps, authentication, templates, and failure-handling options.
- [Test & activate](https://docs.akedly.io/channels/byo-sms/testing.md): Test and activate a BYO SMS integration in the Akedly dashboard: choose an in-coverage recipient, diagnose failures, and see why activation alone does not route.
- [Enable on pipelines & cloning](https://docs.akedly.io/channels/byo-sms/pipelines.md): Enable BYO SMS on an Akedly pipeline, preview effective routing, and clone a registry integration for pipeline-specific coverage and credential settings.
- [Reference](https://docs.akedly.io/channels/byo-sms/reference.md): Learn how BYO SMS routes messages at send time, handles provider failures, bills OTP verifications and accepted utility submissions, surfaces errors, and uses Akedly-managed account settings.

## Optional

- [V1.0 REST API Authentication](https://docs.akedly.io/authentication/v1.md): DEPRECATED: Complete guide to implementing Akedly's 3-step authentication flow. Learn how to request transactions, send OTPs, and verify user authentication through our API.
- [Akedly SDKs](https://docs.akedly.io/sdks.md): DEPRECATED: Official Akedly SDKs for Node.js and Flutter. Simplify OTP authentication with ready-to-use libraries that handle the complete authentication flow.
- [Node.js SDK](https://docs.akedly.io/sdks/nodejs.md): Official Akedly Node.js SDK. Simplify OTP authentication in your JavaScript applications with our easy-to-use wrapper library.
- [Flutter SDK](https://docs.akedly.io/sdks/flutter.md): Official Akedly Flutter SDK. Streamlined Dart interface for OTP authentication in Flutter applications across all platforms.
- [Opt-in WhatsApp Authentication](https://docs.akedly.io/opt-in-authentication.md): DISCONTINUED: Akedly's opt-in WhatsApp authentication service was discontinued on January 1, 2026. This page is kept for historical reference.
- [TOTP Hosted Integration](https://docs.akedly.io/totp-authentication/hosted-integration.md): Complete TOTP authentication implementation using Akedly's hosted pages. Zero UI development required with full white-label support and cross-platform compatibility.
