Skip to main content

Quick start guide

Get up and running with OpenAge age verification in just a few minutes. This guide walks you through implementing basic age verification by using the OpenAge APIs.

Prerequisites​

Before you begin, you'll need:

  1. A Product: Create and configure your product in the Compliance Studio
  2. API Key: Generate your API key from the Developer Settings page of your product
  3. Webhook Endpoint (optional but recommended): Set up a secure HTTPS endpoint to receive verification results
OpenAge Explorer

The best way to get started with development is using the OpenAge Explorer, an open source tool for testing age verification flows. OpenAge Explorer lets you run through complete verification flows while monitoring all traffic, including DOM events, webhooks, and API calls in real time.

Step 1: Create your product​

  1. Visit the Compliance Studio
  2. Sign up or log in to your account
  3. Create a new product for age verification
  4. Configure your product settings (see Compliance Studio Guide for details)
  5. Generate your API key from the Developer Settings

Step 2: Initiate age verification​

Call the /age-verification/perform API to create a verification request. This returns a unique URL that users use to complete their age verification.

tip

Use the interactive API documentation with your API key to quickly generate your Age Verification URL.

Important - For your implementation, this should be a server-to-server call to protect your API key from being exposed in client-side code.

Example request​

POST /api/v1/age-verification/perform
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "criteria": {
    "ageCategory": "ADULT"
  },
  "options": {
    "facialAgeEstimation": {
      "passIfOver": 21,
      "failIfUnder": 14
    }
  }
}

Example response​

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://ui.ageapi.org/verify?token=eyJhbGciOiJFUzM4NCIs..."
}

The jurisdiction parameter ensures compliance with local regulations (such as setting "US-CA" for California requirements), while the ageCategory: "ADULT" criteria verifies users meet the age criteria requirements defined in that jurisdiction.

Step 3: Display the Verification Interface​

Use the returned URL to create an iFrame in your website or app. Users complete their verification through this interface, with available methods automatically adapting to jurisdictional requirements.

HTML implementation​

<div id="verification-container">
  <iframe 
    id="verification-widget"
    src="VERIFICATION_URL" 
    width="100%" 
    height="600"
    frameborder="0"
    allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
  </iframe>
</div>

The iframe presents users with multiple verification methods such as:

  • AgeKey: A reusable and anonymous age-proof generated after an initial verification process
  • Facial Age Estimation: Privacy-preserving age estimation using a device's camera
  • ID Document Verification: Government-issued ID verification
  • Digital Wallet Integration: Support for Apple Wallet, Google Wallet, and Samsung Wallet

The specific methods available depend on the jurisdiction and your product configuration.

Step 4: Handle verification results​

Once the user has successfully completed the age verification, or the user has retried the maximum number of times and hasn't succeeded, you can receive verification results. Implementations should use a combination of client-side and server-side methods: client-side events are best for controlling UI elements, while for data integrity, the actual results should come from either a webhook or a call to /age-verification/get-status.

Client-side (DOM events)​

Use DOM Events for responsive UI updates when verification completes.

const handleMessage = (event) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    if (message.data.status === "PASS") {
      // User passed verification - update UI immediately
      console.log("Age verified:", message.data.ageCategory);
      updateUI();
    } else if (message.data.status === "FAIL") {
      // User failed verification - update UI immediately
      console.log("Verification failed:", message.data.failureReason);
      updateUI();
    }
  }
};

window.addEventListener("message", handleMessage);

Server-side (webhooks, API calls)​

Use webhooks or API calls for data integrity and reliable state management. For data integrity, always verify results with events from webhooks or by calling /age-verification/get-status rather than relying solely on DOM Events.

Webhooks​

Configure your webhook endpoint to receive Verification.Result events:

{
  "eventType": "Verification.Result",
  "data": {
    "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
    "status": "PASS",
    "ageCategory": "adult",
    "method": "id-document",
    "age": {
      "low": 25,
      "high": 25
    }
  }
}

API calls​

Query the verification status with the verification ID with /age-verification/get-status:

GET /api/v1/age-verification/get-status?id=7854909b-9124-4bed-9282-24b44c4a3c97

Response:
{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "status": "PASS",
  "ageCategory": "adult",
  "method": "id-document"
}

Step 5: Test Your Integration​

Before going live, test your integration:

  1. Use the API Documentation to test API calls
  2. Try the verification flow with different age categories
  3. Test webhook delivery to ensure your endpoint receives events
  4. Verify that your iFrame integration works correctly

What's next?​

Now that you've implemented basic age verification, explore these resources to enhance your integration: