Pass-through metadata (optional)

Attach an opaque string to a verification so your backend can correlate the result with whatever context you need — an order reference, a build tag, an internal flow label. AgeWallet does not parse, validate, or interpret the value.

Sending

Include metadata as a query parameter on /authorize, URL-encoded as you would any other parameter.

https://app.agewallet.io/user/authorize?...&metadata=order%3AXYZ-42

Reading it back

The /userinfo response returns the same string under metadata, present only when a value was sent.

{
  "sub": "89",
  "age_verified": true,
  "expires_at": 1765035995,
  "metadata": "order:XYZ-42"
}

Do not use metadata to decide what to update

If your callback reads metadata and marks that order as age-verified, a user can change the reference and apply their verification to a different order. Metadata is a correlation convenience, not a trusted channel.

The safe pattern is to key the association on state instead, which you generate, store server-side, and validate on return:

// Starting the flow
const state = generators.state();
req.session.agewallet = { state, orderId: order.id };

// On the callback, after validating state
const { orderId } = req.session.agewallet;   // trusted: never left your server

Use metadata for what it is good at — tagging requests so they are easy to find in logs and support conversations.

Limits