Skip to content
Akedly
Basics

Quickstart

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 your API pipelines 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.

Build with AI agents
Note:

Before we are able to create an API pipeline, a few things need to be set up. Including your company profile, an API key for your first integration, and the pipeline itself. This guide will cover these steps.

Setup your company profile

Before starting off with anything, you need to let your own customers know who you are. This is a one-time setup, and you can change the information later at any point.

Open the avatar at the top right of the dashboard and pick Company Profile. That menu is the quickest way in from any screen; it also holds My Account, and Organization on enterprise accounts.

View in dashboardAvatar menu → Company Profile(opens in a new tab)

Set your company name, website, description and Cover Photo.

Company Name

The name of your company. Shown to your customers when they are asked to authenticate.

Website

This is the URL of your company's website. It is stored on your Company Profile, but it is not part of the branding data sent to hosted or widget authentication, so your customers do not see it on the verification screen.

Description

A short description of what your company does. Optional.

Cover Photo

The dashboard calls this field Cover Photo; it supplies your company's logo to customers on Akedly-rendered authentication screens. Upload a base64-encoded image data URI in PNG, JPG/JPEG, WebP or GIF format, up to 3 MB, at least 8x8 pixels. The dashboard recommends 1920x1080 PNG with no background so it renders cleanly on light and dark backgrounds.

The widget falls back to this logo only when the widget's own branding does not supply one, and the wide panel image behind the hosted screen is a separate widget branding setting, not this field.

Note:

This logo reaches a customer on any Akedly-rendered screen — the hosted verification page, the V2 widget, and the V1.2 hosted passkey page, which falls back to it the same way. If you build your own UI you decide what to render, but note that some REST responses still carry the branding fields: the TOTP endpoints return companyLogo whether or not you use it.

API keys & where to find them

Your account can have multiple API keys. Each key has its own name, pipeline access and spend limit. Give each backend integration its own key so you can revoke or replace one credential later without disturbing the others.

View in dashboardAccount & Billing → API Keys(opens in a new tab)

See every key on your account, claim the secret of your default key, and manage access, limits and revocation.

The API keys button in the dashboard header opens the same page from any screen. On narrow screens that button collapses to a key icon with no label, so use the sidebar if you are looking for the words.

Claim your default key

A new account starts with a Default API key, so you do not need to create one before your first request. If Show secret once is available, open that row's ⋯ menu and choose it.

The secret is shown one time. Copy it, tick the confirmation, and put it straight into your server-side secret manager. Nothing in the dashboard will show it to you again: the list and the key's own page show only its name, its non-secret prefix and its settings.

Danger:

Keep every API key in trusted backend code and never ship one in browser or mobile code — anyone holding it can send verifications billed to your account. If a secret is lost or exposed, you do not need to interrupt the integration: create a new key if creation is available to you, move your integration onto it, and revoke the old one. If creation is unavailable or rejected because issuance is disabled, you lack permission, or your account is at its ten-key cap, contact Akedly before revoking the old key so you do not take the integration down.

Create a key for an integration

The Create API key control may be visible even when creation is unavailable or rejected for your account. If creation is allowed, the control opens a short form; existing keys keep working either way.

  • Key name — required, up to 100 characters. Name it after the thing that will hold it, like Production backend.
  • Pipeline access — All pipelines, which includes pipelines you create later, or Selected pipelines only, which limits the key to the OTP and TOTP pipelines you pick.
  • Spend limit — an optional lifetime EGP cap for this key. No limit leaves the key uncapped; 0 blocks new billable requests when spend limits are enforced.

Spend limits never reset. Earlier spending counts even if it happened before you set a cap, and accepted work still in progress counts when the cap is enforced. A key that has spent 500 EGP has 500 EGP left under a new 1,000 EGP cap. Replacing a secret keeps that history; an independently created key has its own history.

Pipeline access and spend limits are still being rolled out. For your account, each control may be unavailable, in preview, or enforced. Preview spend limits do not block requests. Budget reservations apply only to keys with a configured cap when spend limits are enforced; uncapped keys and off or preview modes do not use them. Ordinary billing continues in every mode. An account can hold up to ten keys in active or grace state.

A one-time dialog displays the new secret; copy it before closing.

Use and manage keys

  • One key per request. However many keys your account holds, a request carries a single credential — APIKey on the V1.0, V1.2 and Utilities endpoints, apiKey on the V2 widget.
  • Across versions. A key set to all pipelines can serve pipelines on any API version. A key limited to selected pipelines is rollout-dependent: while selected-pipeline access is in preview on your account, an out-of-scope request is recorded but not blocked; otherwise the selected boundary is enforced.
  • Edit. Open a key to change its name, its pipeline access or its spend limit. Editing never changes the secret.
  • Replace after a failed claim. If claiming a key cannot show you its one-time secret, that row offers Create replacement: it issues a fresh secret for the same role, keeps the key's pipeline access and spend history, and retires the old key. For a credential you need to change for any other reason, create a new key, move the integration onto it, and then revoke the old one.
  • Revoke. Revoke a single key when an integration is retired or a secret is exposed. You choose when it stops, from immediately up to 24 hours; that deadline can be shortened later but never extended. Your other keys are untouched.
Note:

Your permissions determine which actions you see: creating, editing, revoking and revealing a secret are separate permissions, so a teammate may see the page without seeing every action. Integrations already running on an existing key keep working — nothing here asks you to replace a credential that is fine.

Setup Your First API Pipeline

A pipeline is the configuration unit for a verification flow. It decides which channels are tried and in what order, which countries you may send to, which security layers run, and where results are delivered. Every API call names a pipelineID, so you need one before you can send anything.

View in dashboardAuthentication → Pipelines(opens in a new tab)

Create and configure pipelines. Note the nav item is "Pipelines" under Authentication — Utilities has a separate list of its own.

Create Pipeline

Click Create Pipeline. Three fields, and the third is the one that matters most:

  • Pipeline Name — anything you like; something that describes what the pipeline is for.
  • Pipeline Description — optional. Add one if it will help you remember what the pipeline does.
  • API Version — V2.0 (recommended) or V1.2. This is the decision that shapes everything after it: which endpoint you call, which security layers exist, and whether the pipeline can back a widget.
Warning:

Pick the version deliberately — it is not a label, it is the contract.

A V1.2 pipeline must be called on /api/v1.2/transactions/…; calling the V1.0 endpoint with it returns 403 USE_V1_2_ENDPOINT. A V1.2 pipeline also cannot be attached to a V2 widget. There is no dual-run mode on a single pipeline, so if you need to move between versions later, create a second pipeline and shift traffic to it rather than flipping this field in place.

Save your webhook signing secret

The moment the pipeline is created you may be shown a signing secret. It is displayed once. Copy it before closing the dialog. The pipeline secret signs V2 widget and V1.2 verification results, Utilities, and OTP channel events; only the V1 verification-result callback remains unsigned.

If the dashboard does not show the secret control, use the webhook secret instructions for the authenticated API fallback, one-time acknowledgement, and regeneration steps.

Warning:

Which webhooks this secret actually signs.

Both OTP callback types use the same backendCallbackURL: route otp.channels.resolved and otp.channels.updated by their top-level eventType, verify the signed raw body, and route verification results by their mainTransaction object — signed on V1.2, unsigned on V1. See OTP channel events for eligibility, payloads, retries, and duplicate handling.

The pipeline page

Open the pipeline to configure it. Active, Test/Live and the API version are shown as controls in the page header — not fields inside a form — and the header toggles save immediately.

Basic Details

  • Pipeline ID — the identifier you pass as pipelineID on every API call. Copy it from here.
  • Pipeline Name and Description — for your own reference in the dashboard.
  • API Version — set at creation; shown here so you can confirm which contract this pipeline is on.

Active and Test/Live live in the page header as toggles, not in this section. A pipeline that is not Active will refuse verifications, so switch it on before you start testing.

Webhooks

This is where you tell Akedly where to deliver results, and where the signing secret lives.

  • Logging Webhook URL — the endpoint we POST to for the legacy verification-result callback on every verification outcome, success or failure. Eligible live OTP requests also receive signed channel events at this URL; isTest: true requests do not. Optional for API-based pipelines, but it is the only way to receive results server-side, so set it unless you intend to poll.
  • View signing secret — retrieve the secret if you did not save it at creation.
  • Test your endpoint — sends a sample request and shows you your server's live response. Use it before you go anywhere near production traffic.
Note:

A front-end redirect URL is used by hosted surfaces such as the V2 widget and the V1.2 hosted passkey flow. A plain V1.2 OTP integration does not need one: when you build your own UI, you handle that navigation yourself.

What's next?

You have a company profile, an API key for your first integration and a pipeline. Now send your first verification.

Your pipeline's API Version decides which guide to follow. V2.0 is the recommended way to verify users with Akedly. Choose V1.2 instead if you cannot embed an iframe or open a system browser.

  • V2.0 Widgets

    —

    a hosted verification screen you embed in an iframe. Akedly runs the code flow, captcha, device checks and rate limits. It needs a V2 pipeline, so set the API Version to V2 when you create it.

  • V1.2 REST API

    —

    you build the screens and call three endpoints: get a challenge, send the OTP, verify. Akedly Shield adds proof-of-work and Turnstile on the client. It needs a V1.2 pipeline.

Warning:

Call the endpoint that matches your pipeline's version.

A V1.2 pipeline sent to the V1.0 endpoint returns 403 USE_V1_2_ENDPOINT, and a V1.2 call against a pipeline with no version set returns 403 INVALID_API_VERSION. If you are unsure which version a pipeline is on, the header of its detail page shows it.

Not sure which to build on? Compare the integration methods side by side.

Next: after the first successful verification, turn on passkeys so the next sign-in is a biometric or screen lock. OTP once, Passkey forever.