Skip to main content

API Reference

Welcome​

AgeKey provides a comprehensive API for privacy-preserving age verification. The API is built on OpenID Connect (OIDC) standards, making it familiar to developers who have worked with OAuth 2.0 or social login integrations.

Authentication​

All API endpoints require proper client credentials and use standard OIDC authentication flows.

Client credentials​

You'll need to obtain these from AgeKey:

  • client_id: Your app identifier
  • client_secret: Your app secret (keep this secure!)

Security best practices​

Important

Never expose your client_secret in front-end code. Always keep it secure on your server.

  • Store credentials securely
  • Implement proper state and nonce validation
  • Validate all JWT tokens on your server

Base URLs​

Use AgeKey Service:

https://api.agekey.org/v1/oidc/use

Create AgeKey Service:

https://api.agekey.org/v1/oidc/create

Optional language preference​

On browser redirects to /v1/oidc/use (including when you include the agekey.upgrade scope for upgrades) and /v1/oidc/create, you can add a language query string parameter with an IETF BCP 47 tag (for example en-US, pt-BR) to set the AgeKey UI language for that request. When you omit it, the UI follows the visitor's browser language preferences.

Verification Keys:

https://api.agekey.org/.well-known/jwks.json

Integration flows​

AgeKey supports two main integration patterns:

Use AgeKey flow

For users with existing AgeKeys to verify their age quickly.

Create AgeKey flow

For users to save verification results as AgeKey for future use.

OpenID Connect discovery​

AgeKey supports OIDC discovery for easy integration with certified libraries.

Use AgeKey Discovery:

https://api.agekey.org/v1/oidc/use/.well-known/openid-configuration

Create AgeKey Discovery:

https://api.agekey.org/v1/oidc/create/.well-known/openid-configuration

Response formats​

Age threshold results​

When using the Use AgeKey flow, you'll receive age threshold results in this format:

{
  "age_thresholds": {
    "13": true,
    "18": false,
    "21": false
  }
}

Error responses​

Standard OIDC error responses and error redirect parameters are used.

Support​

Get help​

Contact the support team for integration assistance: support@AgeKey.org