API Reference

This page documents the exact browser-facing contract used by the SDK.

Use it when you want API-style reference tables rather than implementation walkthroughs.

End-To-End Sequence

Environments

Create Verification Session

Starts a browser verification flow and returns a redirect URL as plain text.

Endpoints

Headers

Query Parameters

Request Body

Success Response

Example response body:

https://aldersverificering.dk/oidc/authorize?client_id=...

Real test example:

Request:

POST https://test.api.aldersverificering.dk/api/v1/oidc/create?RedirectUri=https%3A%2F%2Funqverify-app.myshopify.com%2F&AgeToVerify=18

Response body:

https://pp.netseidbroker.dk/op/connect/authorize?client_id=0b5ac04e-5dbb-4bb8-a697-93152896a2f6&redirect_uri=https%3A%2F%2Ftest.api.aldersverificering.dk%2Fapi%2Fv1%2Foidc%2Fcallback%3FredirectUri%3Dhttps%253A%252F%252Funqverify-app.myshopify.com%252F%26nonce%3D17959b87-7d8a-4aac-b88c-05a005bb194f%26internalCustomerId%3D6952c411cd0a2cfed100fcc5%26internalRequestEventId%3D69bd093ceef79d9928ef28c0&response_type=code&scope=openid%20age_verify%3A18&prompt=login&nonce=17959b87-7d8a-4aac-b88c-05a005bb194f

That returned URL is the MitID broker portal entrypoint. Your frontend should treat it as an opaque redirect target and send the browser to it exactly as returned.

Response URL Semantics

You should not parse business logic out of this URL. Use it only as the next redirect target.

Error Response

Example error handling shape:

const response = await fetch(url, options)

if (!response.ok) {
  const errorBody = await response.text()
  throw new Error(`API error: ${response.status} - ${errorBody}`)
}

Example Request

curl -X POST \
  'https://test.api.aldersverificering.dk/api/v1/oidc/create?RedirectUri=https%3A%2F%2Fshop.example.com%2Fverify-result&AgeToVerify=18' \
  -H 'Content-Type: application/json' \
  -H 'x-public-key: pk_test_your_key'

Redirect Callback Contract

After the user completes verification, the browser returns to your RedirectUri.

Query Parameters Returned To Your Callback Page

Expected Callback Behavior

Verification JWT Claims

Binding a result to an account

For account approval, create a fresh reference on your backend for each verification attempt. Use crypto.randomBytes(32).toString('base64url') in Node.js and store it with the logged-in account, expected age threshold, environment, expiry and an unused flag. Call the create endpoint from your backend with merchant_reference in the query and the usual x-public-key header. Redirect the browser to the returned broker URL.

Keep the reference on your backend until the signed result arrives. The public API key allows anyone who possesses it to start a flow, so predictable references such as user IDs, email addresses or order numbers are unsuitable. Keep references out of browser state, callback URLs, analytics and request logs. The API checks the format and length, while your backend is responsible for cryptographic randomness and single use. The reference binds an attempt to an account, without establishing a person's identity or preventing someone from deliberately sharing their flow.

On return, validate the raw JWT on your backend using the configured environment's JWKS, RS256 algorithm, expected issuer and expiration. Require a successful result, an age threshold at least as high as your requirement, and an exact match between the signed merchant_reference and the pending reference for the logged-in account. Reject missing, mismatched, expired or already-used references. Consume the reference and approve the account in one database transaction so concurrent callbacks can approve it only once. Tokens from older flows without this claim cannot approve an account through this integration.

UNQVerify stores the reference on the verification event and signs that stored value. Callback query parameters cannot replace it. Callback recovery uses the same stored reference and completed retries return the original JWT. The claim is also included on unsuccessful results, so always check the verification result before approval.

JWKS Endpoints

Use the token issuer to choose the correct JWKS endpoint for RS256 signature verification.

Popup Message Contract

If you use popup flow, the callback page posts the verification result back to the opener window.

Success Message

Example:

{
  "type": "UNQVERIFY_RESULT",
  "payload": {
    "iss": "https://test.aldersverificering.dk",
    "exp": 1773980000,
    "aldersverificeringdk_verification_result": true,
    "aldersverificeringdk_verification_age": 21
  }
}

Failure Message

Example:

{
  "type": "UNQVERIFY_FAILURE",
  "error": "User does not meet the age requirement",
  "code": "UNDER_AGE"
}

Recommended Outcome Codes

Storage Contract Used By The SDK

If you want parity with the current SDK behavior:

Related Pages

1. Redirect Flow
2. Popup Flow
3. Token Validation