Skip to main content

Quick start: Verify with AgeKey

Implement AgeKey verification in four simple steps.

Fastest way to get started

The quickest way to see AgeKey in action is to run the complete Next.js sample project. It's an open source implementation showing both Use AgeKey and Create AgeKey flows with working code you can copy and adapt.

1) Set up your credentials​

Get your client credentials​

Contact AgeKey to obtain your client_id and client_secret for AgeKey integration.

Register redirect URIs​

When contacting AgeKey for credentials, provide the redirect URIs you plan to use. These are the locations where your users are redirected to resume the age verification flow after using or saving an AgeKey.

This example uses https://yourapp.com/agekey/callback as a placeholder redirect URI. Replace this URL with your actual registered redirect URI.

2) Install dependencies​

npm install openid-client

3) Build AgeKey redirect URL with claims​

Your verification button redirects to AgeKey with your requested age thresholds in claims.

Using an iframe?

If you're embedding the Use AgeKey flow in an iframe, you must include the publickey-credentials-get permission in the allow attribute:

<iframe src="https://api.agekey.org/v1/oidc/use" 
        allow="publickey-credentials-get">
</iframe>
// Browser-side using oidc-client's UserManager to handle state/nonce
import { UserManager } from 'oidc-client';

const settings = {
  authority: 'https://api.agekey.org/v1/oidc/use',
  client_id: 'your-client-id', // replace
  redirect_uri: 'https://yourapp.com/agekey/callback',
  response_type: 'id_token',
  scope: 'openid',
  // AgeKey requires the claims parameter with requested thresholds
  extraQueryParams: {
    claims: JSON.stringify({ age_thresholds: [13, 18] })
  }
};

const userManager = new UserManager(settings);

async function verifyWithAgeKey() {
  // Automatically generates and stores state/nonce
  await userManager.signinRedirect();
}

// Example usage in your UI:
// <button onClick={verifyWithAgeKey}>Verify with AgeKey</button>

4) Handle the AgeKey callback​

The OIDC library processes the response for you, validating state, nonce, and the JWT ID Token, then exposes the results so you can read age_thresholds.

import { UserManager } from 'oidc-client';

const userManager = new UserManager({
  authority: 'https://api.agekey.org/v1/oidc/use',
  client_id: 'your-client-id',
  redirect_uri: 'https://yourapp.com/agekey/callback',
  response_type: 'id_token',
  response_mode: 'query',
  scope: 'openid'
});

// On your callback page/component
async function handleAgeKeyCallback() {
  try {
    // Parses URL, validates state/nonce, and returns the user with id_token claims
    const user = await userManager.signinRedirectCallback();
    const results = user.profile?.age_thresholds; // e.g., { "13": true, "18": false }

    if (results?.['18']) {
      // 18+ content allowed
    } else if (results?.['13']) {
      // 13+ content allowed
    } else {
      // Under 13
    }
  } catch (err) {
    console.error('Verification failed:', err);
  }
}

// Call this on load of your callback route/page
handleAgeKeyCallback();

What's next?​

Using an AgeKey

Dive deeper into parameters, security, and validation for the Use AgeKey flow.

Creating an AgeKey

Let users save a reusable credential after completing age verification.