Integrate in 15 minutes

• How it works
• Quick start
• Live key vs test key
• Verify the token
• Account API
• Recover a lost key
• Key rotation
• Domain whitelist
• Account status
• Troubleshooting
• Reference

Integration is a two-side handshake:

• Front end: the widget verifies the visitor and hands your page a single-use verification token (a signed JWT).
• Back end: your server posts that token to POST /v1/verify-token. That call is the billable moment: one success is one verification.

All calls use base URL https://api.agewarden.ai and JSON.

You get three keys when you sign up:

Paste this into a page, drop in your aw_test_ key, and open it over http://localhost:

<div id="age-verify"></div>
<script
  src="https://bouncer.agewarden.ai/loader.js"
  data-site-key="aw_test_YOUR_TEST_KEY"
  data-target="#age-verify"
  data-widget-version="1">
</script>

Test traffic never bills, and localhost / 127.0.0.1 are always allowed with a test key, no whitelist entry needed. A live (aw_live_) key on a non-whitelisted origin (including localhost) is refused by design; that is the "not available on this site" state.

Your account's copy-paste snippets (test and live), prefilled with your widget keys, appear once on the welcome page right after signup. Save them then; otherwise use the template above and drop in your key.

Both keys share the same domain whitelist. Swap the key value in the widget snippet to go live.

Exchange the token your client posted for the verdict by calling POST /v1/verify-token. This is the billable moment: one success equals one verification.

Request

POST https://api.agewarden.ai/v1/verify-token
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
    "token": "<verification token from the widget>"
}

cURL

curl -X POST https://api.agewarden.ai/v1/verify-token \
    -H "Authorization: Bearer $AGEWARDEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"token":"<verification-token>"}'

Response: 200 OK (valid token)

{
    "valid": true,
    "verification_id": "ver_01HZ...",
    "result": "ALLOW"
}

valid: true means the token was genuine and has been consumed. verification_id is the durable receipt; log it for audit and idempotency. result is one of:

• ALLOW (Approved): age confirmed. Billable.
• BLOCK (Declined): not confirmed or under age. Billable.
• RETRY: the recording was inconclusive. It isn't billed and prompts the user to re-record. Not billable.

Treat only ALLOW and BLOCK as terminal. On RETRY, re-prompt the user to record again; don't grant or deny access. Calling /v1/verify-token on a RETRY returns valid: true, result: "RETRY" and is never metered. A verification that stays inconclusive across repeated retries is finalized as BLOCK (Declined), which is billable.

Response: 200 OK (token-level rejection)

Token problems return 200 with valid: false and an error string. The request was well-formed; the token simply isn't usable. Surface these to the visitor as "please try again," not as a server failure.

Errors: auth and request

POST /v1/account manages your account: one endpoint, four actions, same auth as verify-token (Authorization: Bearer YOUR_API_KEY). Auth failure (missing key, wrong key, or account status not active / past_due) returns 401 {"error": "unauthorized"}. The Account dashboard calls these routes directly.

whitelist validation errors return 400 with one of: hostnames must be a list, too_many_hostnames, hostname_must_be_string, hostname_must_not_include_scheme, hostname_must_not_include_path. Unknown action strings return 400 {"error": "unknown_action"}.

Lost your api_key? POST /v1/recover is unauthenticated and runs in two phases. Phase is inferred from the body: email triggers phase 1, token triggers phase 2.

Phase 1: request the link

POST https://api.agewarden.ai/v1/recover
Content-Type: application/json

{ "email": "you@example.com" }

Always returns 202 Accepted with body {"status": "ok"}. We don't reveal whether the email matched an account, to prevent enumeration. If it matches a Stripe customer record, a magic link is sent. The link is valid for 15 minutes and is single-use.

Phase 2: exchange the token

POST https://api.agewarden.ai/v1/recover
Content-Type: application/json

{ "token": "<token from the magic link>" }

Returns { "api_key": "<new key>", "prev_expires_at": <epoch> }. Shown once. The new key arrives under api_key (the rotate action returns it under key). Your previous api_key keeps working for 24 hours, then stops authenticating.

Errors: 401 {"error": "link expired or already used"} if the token in phase 2 has been redeemed, has expired past its 15-minute TTL, or doesn't exist. Request a new link.

Every key (api_key, widget_key_live, widget_key_test) rotates from the dashboard or via /v1/account action rotate. Rotation is non-disruptive:

• A new raw key is returned once, under the key field. We store only its SHA-256 hash; if you lose it, rotate again.
• The old key keeps working for 24 hours. The response includes prev_expires_at as a unix epoch: the exact moment the old key dies.
• During that window, both keys authenticate.
• After prev_expires_at passes, only the new key works.

Roll the new key into production config, CI secrets, and edge caches at your own pace; nothing breaks the moment you click the button.

The widget refuses to run on any origin not on your whitelist. Set the list from the Account dashboard or via /v1/account action whitelist. Send hostnames under the hostnames field; read them back under domain_whitelist.

• Hostnames only. No scheme, no port, no path. example.com, not https://example.com/. Entries with :// or / are rejected as 400.
• Exact match by default. List subdomains explicitly (app.example.com), or use a leading *. wildcard (*.example.com matches every subdomain but not the bare apex).
• Max 50 entries. Talk to us if you legitimately need more.
• One list, both keys. Live and test keys validate against the same whitelist.
• Replace, not append. A whitelist call replaces the whole list. To add one domain, send the existing list plus the new one.
• Test-key dev exception. With a test key, localhost and 127.0.0.1 are accepted regardless of the whitelist.

Every /v1/verify-token request and every widget load checks your status:

A past_due account is not blocked; that's the point of the grace period. Only inactive or suspended produces 403 (verify-token returns {"valid": false, "error": "account_inactive"}; /v1/account returns {"error": "unauthorized"}).

• Billing is monthly in arrears. Stripe totals successful verify-token calls at month-end and charges the card on file. No upfront fee, no commitment.
• New accounts get a $10 credit on the first invoice: roughly 100 verifications at the entry band. Applied automatically at onboarding.
• Disputes don't lock your account. Chargeback an invoice and your keys keep working; we don't auto-suspend on dispute.
• Cancellation is one click in the Stripe billing portal (/v1/account action portal). Keys keep working through the end of the paid period; then the account moves to inactive.
• Enterprise accounts never auto-suspend on payment failure: invoices are net-30 ACH or wire, status changes are manual, and the Stripe portal is unavailable (portal returns 400).

Base URL: https://api.agewarden.ai. All requests are JSON. Authorization: Bearer <key>. No other header schemes are accepted.

Something missing? email us.