Docs

Quickstart

Three steps, all server-to-server plus one redirect: create a verification session, send your user to the hosted flow, and receive the signed result. Test mode is free and unlimited — the snippets below work as-is once you swap in a test key from your dashboard.

  1. 01

    Create a verification session

    From your server, using your secret key. Set required_age to 16 or 18, and return_url to where the user should land once they’re done.

    shell
    curl https://5do9r1erj7.execute-api.ap-southeast-2.amazonaws.com/v1/verification-sessions \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "required_age": 18,
    "methods": ["face_estimation", "id_document"],
    "return_url": "https://yoursite.com/age/verified"
  }'
    javascript · node
    const res = await fetch("https://5do9r1erj7.execute-api.ap-southeast-2.amazonaws.com/v1/verification-sessions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    required_age: 18,
    methods: ["face_estimation", "id_document"],
    return_url: "https://yoursite.com/age/verified",
  }),
});

const session = await res.json();
// session.url → send the user here (see step 2)

    You get back a one-time hosted URL, good for 30 minutes:

    json · response
    {
  "id": "vs_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "url": "https://d21c67ryshh77h.cloudfront.net/v/vs_01ARZ3NDEKTSV4RRFFQ69G5FAV#st=eyJhbGciOi...",
  "status": "created",
  "required_age": 18,
  "methods": ["face_estimation", "id_document"],
  "return_url": "https://yoursite.com/age/verified",
  "mode": "test",
  "created_at": "2026-07-12T04:00:00.000Z",
  "expires_at": "2026-07-12T04:30:00.000Z"
}

    See the full request/response shape on the REST API page.

  2. 02

    Send your user to the hosted flow

    Redirect the user to session.url directly, or open it from the browser with the ~1 kB JavaScript SDK, which pops a centered window and reports the result without leaving your page.

    javascript · plain redirect
    // Simplest integration: just navigate the user there.
window.location.href = session.url;
    javascript · sdk popup
    import { AgeAssure } from "@ageassure/js";

AgeAssure.open({
  url: session.url,
  onComplete: ({ sessionId, status }) => {
    // status is "passed" | "failed" — update your UI immediately.
    // Treat this as a fast, optimistic signal; the webhook (step 3)
    // is the record of truth.
  },
});

    Full SDK reference on the JavaScript SDK page. There is nothing to store on your side during this step — the image is analysed and deleted before the session ever resolves.

  3. 03

    Receive the result

    The outcome reaches you up to three ways, and you can use any or all of them:

    • The SDK’s onComplete — fastest, client-side, good for updating UI immediately.
    • The redirect back to return_url — AgeAssure appends ?session_id=vs_...; call GET /v1/verification-sessions/:id server-side to confirm the outcome before acting on it.
    • A verification_session.completed webhook — server-to-server, signed, and retried on failure. This is the record of truth; treat the other two as fast, optimistic signals.
    http · webhook delivery
    POST https://yourapp.com/webhooks/ageassure
AgeAssure-Signature: t=1752300000,v1=5b3f...
AgeAssure-Event: verification_session.completed

{
  "id": "evt_...",
  "type": "verification_session.completed",
  "created": "2026-07-12T04:00:31.000Z",
  "data": {
    "id": "vs_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "status": "passed",
    "required_age": 18,
    "method": "face_estimation",
    "confidence": "high",
    "mode": "test",
    "metadata": {}
  }
}

    Add an endpoint on your dashboard’s Webhooks page and verify the AgeAssure-Signature header — full scheme and code on the Webhooks page.