Akedly

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.

Before we are able to create an API pipeline, a few things need to be set up. Including your company profile, your API key, 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

Set your company name, website, description and company logo.

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.

Company logo

This is your company's logo, shown to your customers on Akedly-hosted 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.

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 Key & Where to Find It

Every API request authenticates with your API key. There is one key per account, and it is the same key across V1.2 and V2.0.

1. Click "View API Key" — it sits in the top bar and is reachable from any screen.

Where to find the View API Key button

2. The dialog gives you three actions. The key is masked by default — use Show API Key to reveal it, Copy API Key to put it on your clipboard, and Rotate API Key if it is ever exposed.

API Key dialog

Keep your API key on your server and never ship it in browser or mobile code — anyone holding it can send verifications billed to your account. If it does leak, rotate it yourself from this dialog; you do not need to contact us. Rotating invalidates the old key immediately, so update your backend in the same change.

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

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

Pipelines list

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 — V1.2 (Recommended) by default. 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.

Create a pipeline

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 are shown a signing secret. It is displayed once. Copy it before closing the dialog.

Pipeline created — save your webhook secret

If you lose it you can regenerate a new one from the pipeline's Webhooks section, but the old secret stops working the moment you do.

Which webhooks this secret actually signs. Signature verification is live for V2 widget and Utilities webhooks. OTP callbacks from the REST API — V1.0 and V1.2 alike — are currently delivered without svix-* headers. So do not build signature checking into a V1.2 callback handler expecting those headers; they will not arrive, and a handler that rejects unsigned requests will drop every legitimate result. Treat your callback URL as guessable and verify by other means: confirm the transactionID against your own record before acting on it.

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.

Pipeline details

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.

Webhooks section

  • Logging Webhook URL — the endpoint we POST to on every verification outcome, success or failure. 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.

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 and a pipeline. Now send your first verification.

Your pipeline was created on V1.2, so go straight to the V1.2 guide — it matches what you just built:

  • V1.2 REST API — you build the UI, Akedly handles delivery, and Akedly Shield adds proof-of-work and Turnstile on the client. This is the recommended path and the one your pipeline is already configured for.
  • V2.0 Widgets — a drop-in hosted widget instead of building your own screens. It needs a V2 pipeline, so create a second one with the API Version set to V2.

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.

Was this page helpful?