Skip to main content

2 posts tagged with "use-agekey"

View All Tags

Clearer UX flow guide, new mobile guide, and theme parameter

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:

Updated docs​

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.

Use AgeKey redirect parameter create_requested

We've added a new query string parameter to the Use AgeKey flow redirect so you can support users who don't have an AgeKey yet without sending them back to choose a different verification method.

What's New​

create_requested on Use AgeKey redirect​

When a user starts the Use AgeKey flow but does not have an AgeKey, the AgeKey service can show a "use or create AgeKey" dialog. If the user chooses to create an AgeKey, they are now redirected to your redirect_uri with a create_requested=true query parameter (and no id_token).

Your app can detect this and send the user to complete verification with another method (such as ID document scan). Once that verification succeeds, direct them to the Create AgeKey flow. They can then continue without having to go back and pick a different method from scratch.

Updated docs​

  • Using an AgeKey — flow overview, callback handling, and a table of redirect query parameters
  • Use AgeKey API — response section now documents create_requested and the two redirect outcomes

How to handle it​

On your Use AgeKey callback page, read the query string and branch on create_requested:

  • If create_requested=true, send the user to your verification flow so they can complete verification with another method (such as /verify). After successful verification, direct them to the Create AgeKey flow.
  • Otherwise, continue with id_token validation as before.

No changes are required if you do not want to support this path; the parameter is only set when the user explicitly chooses to create an AgeKey from the dialog.