One post tagged with "upgrade-agekey"

We've expanded the AgeKey integration guides and added a new theme query parameter so you can match the AgeKey-hosted UI to your app's appearance.

What's New​

UX flow guide rewritten around hosting boundaries​

The UX flow guide now makes it explicit which screens you (the developer) build and host, and which screens AgeKey renders on agekey.org. The high-level rule: whenever you redirect a user to agekey.org, AgeKey owns the UI for that step and will redirect the browser back to your configured redirect_uri when the user finishes or abandons it.

Specifically, you'll see:

• A new "Who hosts each part of the experience?" section that lists every screen on each side
• Per-step (Your app) and (AgeKey-hosted) annotations on the Use, Create, and Upgrade flows
• A color-coded decision-tree diagram (blue for your-app screens, purple for AgeKey-hosted screens, green for the final access state) with an inline legend

New mobile apps guide​

The new Mobile apps guide covers how to embed AgeKey flows in iOS and Android apps, including which webview components support WebAuthn (required for passkey-based AgeKeys), recommended options such as Android Custom Tabs and iOS ASWebAuthenticationSession, and how to handle the OIDC redirect back into your app.

New theme query parameter on AgeKey-hosted flows​

You can now pass an optional theme query parameter when redirecting users to the AgeKey-hosted authorization URLs. It accepts:

• light
• dark
• system (follows the visitor's OS preference)

When omitted, the UI defaults to light mode. This applies to:

• The Use AgeKey authorization endpoint (also used for the Upgrade flow)
• The Create AgeKey authorization endpoint

Updated docs​

• UX flow: hosting-boundary section, annotated steps, color-coded diagram
• Mobile apps: platform-specific guidance for embedding AgeKey flows
• Use AgeKey API and Create AgeKey authorization API: new theme parameter
• Create AgeKey guide: theme added to the optional parameters table

How to use the theme parameter​

Append theme to the AgeKey authorization URL alongside any existing optional parameters such as language:

const params = new URLSearchParams({
  scope: 'openid',
  response_type: 'id_token',
  client_id: 'your-client-id',
  redirect_uri: 'https://yourapp.com/agekey/callback',
  state,
  nonce,
  claims: JSON.stringify({ age_thresholds: [13, 18] }),
});

params.set('theme', 'dark');

const authUrl = `https://api.agekey.org/v1/oidc/use?${params.toString()}`;
window.location.href = authUrl;

No changes are required if you want AgeKey to use the default light theme; the parameter is only needed when you want dark mode or OS-matching behavior.