Customization
Overview
The screens AgeKey hosts on agekey.org can be styled to match your brand. Colors, typography, text alignment, and button shape are set with query parameters on the authorization request, and your application's logo is uploaded in the AgeKey Dev Portal.
None of this changes what AgeKey verifies or what it returns to you. These parameters affect presentation only.
How it works
Add any of the parameters below to the authorization URL you redirect the user to. Both the Create AgeKey and Use AgeKey flows accept them, and AgeKey applies them before the first screen paints.
https://api.agekey.org/v1/oidc/use
?client_id=ak_live_...
&redirect_uri=https://example.com/callback
&scope=openid
&response_type=id_token
&nonce=...&state=...&claims=...
&primary_color=e91e63
&button_radius=16
&font=Nunito
Every value is validated. When a value fails validation AgeKey ignores it and uses the default instead, so a malformed parameter can never break the verification flow or block a user.
Each parameter has a default. Send a parameter only when you want to override it, and leave the rest out.
Appearance parameters
| Parameter | Values | Default | Description |
|---|---|---|---|
primary_color | 6-digit hex | 3700c1 | Primary buttons, the AgeKey wordmark, the Details Requested outline, and the check marks. The deeper shades in the button gradient and wordmark are derived from it. |
secondary_color | 6-digit hex | 3700c1 | Link-style actions, such as Already have an AgeKey? on the Use AgeKey screen. |
text_color | 6-digit hex | 101828 | Headings and body copy. The muted tone used for supporting text is derived from it, so it stays readable on your background. |
background_color | 6-digit hex | ffffff | The sheet background, and the Details Requested panel that sits on it. |
text_align | left, center, right | left | Alignment of the title and description. |
button_radius | 0 to 32 | 8 | Button corner radius, in px. Larger values are clamped to 32. |
gradient | true, false | true | Set false to flatten the button and wordmark gradients to a solid primary_color. |
font | Font family name | AgeKey default | Any Google Fonts family, such as Inter or Playfair Display. Names can contain letters, digits, spaces, and hyphens. |
Color values
Hex colors are 6 digits and the leading # is optional. Because # starts the fragment of a URL, send it encoded as %23 or leave it out:
&primary_color=e91e63 recommended
&primary_color=%23e91e63 encoded, also fine
&primary_color=#e91e63 truncates the URL
Custom fonts
A custom font loads from Google Fonts after the first paint, so it never delays the screen. Until it arrives, or if the name doesn't match a Google Fonts family, text renders in the AgeKey default font.
Setting any appearance parameter to a valid value forces the light theme, and the theme parameter is ignored for that request. Custom palettes are designed against light backgrounds, so AgeKey never mixes them with dark-mode styling.
Try it
Adjust the parameters and watch the Use AgeKey screen respond. Switch between the mobile and desktop viewports to see how the same screen adapts. The query string below the preview lists only what differs from the defaults, ready to append to your authorization URL.
The application logo switch is grouped separately because it isn't a query parameter. It shows the difference an upload in the Dev Portal makes: with a logo in place, your mark sits beside the AgeKey wordmark, joined by a row of connector dots that picks up your primary color. Without one, AgeKey shows its own wordmark alone.
Prove your age once. Never again.
An AgeKey is a free, anonymous proof of age saved on your phone. Create it now and skip verification next time, here and on other sites that accept it.
Details Requested
Behavior parameters
These parameters change what the screen does rather than how it looks.
| Parameter | Values | Default | Description |
|---|---|---|---|
theme | light, dark, system | light | Color scheme. system follows the user's device setting. Ignored when an appearance parameter is set. |
learn_more | true, false | true | Set false to hide the Learn More link below the description. |
language | Locale tag | Automatic | Sets the interface language, such as fr or pt-BR. Without it, AgeKey uses the user's previous choice, then their browser language. Unsupported tags are ignored. |
Your application logo
The logo beside the AgeKey wordmark isn't a query parameter. Upload it in the AgeKey Dev Portal:
- Sign in and choose your organization.
- Open Applications and select your application.
- Upload or replace the logo in the application settings.
Logos are stored per client_id, so your test and live applications can carry different logos. A new logo takes effect on the next request, with no redeploy needed.
Worked example
A pink, flat, left-aligned treatment with rounded buttons, a custom font, and the Learn More link hidden:
&primary_color=e91e63
&secondary_color=880e4f
&text_color=212121
&background_color=fff5f8
&text_align=left
&button_radius=16
&gradient=false
&font=Nunito
&learn_more=false
Next steps
- Use AgeKey covers the authorization request these parameters attach to.
- UX flow explains which screens you own and which AgeKey hosts.
- Mobile apps covers presenting these screens inside a native app.