Skip to content
Akedly
Headless

Headless REST API

Headless is the REST API for teams that want full control of the UI. You call three endpoints (get a challenge, send the OTP, verify) and Akedly Shield adds proof-of-work and Cloudflare Turnstile on the client when the integration has them on. No iframe is required.

When to choose Headless

  • You build your own screens and want full UI control.
  • You cannot embed an iframe or open a system browser: a pure REST backend, or a native app that cannot hand off to a system browser.
  • You want the Shield SDKs for Web, iOS, Android, Flutter or React Native.

Choose Gateway if you would rather have Akedly run the verification screen.

Page map

  1. Set up the integration: credentials and where they come from.
  2. Get a challenge and send the OTP: the two requests and the OTP message language.
  3. Solve the challenge: proof-of-work, Turnstile and the Shield SDKs.
  4. Verify and callbacks: the verify request and the webhook your backend receives.
  5. Channels and security: channel choice, adaptive difficulty, challenge expiry and Turnstile.
  6. Errors and troubleshooting: error codes by category.
  7. Migrate from V1.0: how the three V1.0 server calls map to the Headless flow.

Next: after a verified OTP, turn on passkeys so returning users skip the code. OTP once, Passkey forever.


What is Akedly Shield?

Headless wraps the familiar V1 REST API with Akedly Shield — a client-side security layer that can enforce Proof-of-Work and Cloudflare Turnstile according to the integration configuration. Same REST model, full UI control.

Traditional OTP services are plain REST APIs — any bot can call them, draining your SMS budget with fake verification requests. Akedly Shield adds a client-side proof layer when the corresponding integration controls are enabled: before your user receives an OTP, the client may need to:

  1. Solve a Proof-of-Work challenge — computational cost deters automated abuse
  2. Pass Cloudflare Turnstile verification — bot detection without user friction

This "shield" sits between attackers and your OTP integration. Unlike other services where you bolt on captcha yourself, Shield is built into the API flow. No iframe required (unlike gateway screens) -- you keep full UI control.

FeatureV1.0Headless (Shield)Gateway
Integration StyleREST APIREST API + Shield SDKIframe Gateway screen
UI ControlFull (you build it)Full (you build it)Managed by Akedly
Proof-of-WorkNoneConfigurable per integration (Shield SDK-supported)N/A (screen-managed)
Captcha ProtectionImplement your ownConfigurable per integrationBuilt-in (gateway screen)
Rate LimitingImplement your ownIntegration-levelScreen-level
Circuit BreakerImplement your ownIntegration-levelScreen-level
Device FingerprintingImplement your ownNot provided by this REST routeScreen-level
PPSA PricingNoNoEligible
Security CoverageDIY~80% of GatewayFull

Authentication Flow

Headless uses a 4-step flow. The challenge response tells the client whether PoW is required; Turnstile is likewise conditional. The client then makes two server calls to complete the OTP lifecycle.

  • Name
    1. Get Challenge
    Type
    GET
    Description

    Request the challenge and Turnstile configuration from the server. PoW may be disabled for the integration.

  • Name
    2. Solve Challenge
    Type
    client-side
    Description

    If challengeRequired is true, use a Shield SDK to solve the PoW challenge. Obtain a Turnstile token only when turnstile.required is true.

  • Name
    3. Send OTP
    Type
    POST
    Description

    Submit the applicable proofs along with the user's phone number or email address, and the real end user's IP in the x-end-user-ip header. The server validates enabled proofs and sends the OTP.

  • Name
    4. Verify OTP
    Type
    POST
    Description

    Submit the user's OTP input for verification. Identical to V1.0 Step 3.


Stay Updated