Add a gateway screen
Akedly hosts the whole verification screen. You embed it and read the result.
Formerly “Add the V2 widget”
Gateway was called V2.0 Widgets. This page was at /tutorials/add-the-widget; old links still work.
Add a gateway screen
Creating the integration, attaching a gateway screen, and embedding it.
Gateway screen or REST — pick one deliberately
The gateway screen means no UI work and no proof-of-work handling, at the cost of Akedly owning the screen your user sees. If you need your own design, use the Headless REST API instead.
What you need
- A gateway integration — a headless integration cannot have gateway screens
- A page you can paste a snippet into
Steps
Create a gateway integration.
In Integrations, select New integration, then Verify users and Gateway. It comes with its first gateway screen; copy the screen's Gateway secret on the last step, because it is shown once. A new integration starts on, in Test mode, so you can try it right away; before it goes Live, add the Return URL and Server URL on its Webhooks tab.
View in dashboardIntegrations(opens in a new tab)Create a gateway integration. Add more screens later from its Gateway screens tab.
Check the screen.
The gateway screen carries the branding, the bot checks and the rate limits. Open it from the integration's Gateway screens tab.
Brand it.
Company name, logo and colours come from the Branding Studio (the integration's Branding tab) and from your business details, not from code.
Embed it.
Your backend creates an attempt and your page opens the returned
iframeUrl. The exact attributes are on the Gateway page.Read the result.
Two ways, and you usually want both — the redirect back to your front end for the user's benefit, and the backend webhook for the truth.
If your server misses the gateway screen's backend webhook, Akedly retries it for about 8½ hours
(the schedule). Retries can deliver the same result twice, so skip a
svix-id you have already processed. If the verification matters, still confirm it from
the API rather than treating the webhook as your only record.
When it breaks
- The gateway screen refuses the integration — it is headless. Create a gateway integration; an integration's type cannot be changed afterwards.
- Verification succeeds but nothing reaches your server — check the callback URL is set and answers a
2xxwithin 10 seconds, without redirecting. Failed deliveries are normally retried for about 8½ hours — see Retries. - Codes rejected at the last step — a fixed six-digit input. Gateway screens can issue 4, 5 or 6 digits.
- The gateway screen says “Turn on cookies to continue” — the browser blocks website storage, which the gateway screen needs. The user follows the on-screen steps; in an iframe, add
clipboard-writetoallowso Copy link works. See When the browser blocks cookies.
Where to go next
Gateway
—every attribute, event and error
Passkeys
—let returning users skip the code entirely
Receive a webhook
—handling the result properly
