Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The verifier app

The verifier app is a web application that the credential verifier serves. It gives an operator a browser interface to start credential verification transactions and to read their results. The app has two parts: a single-page application (SPA) and a JSON API. The credential verifier serves the SPA from the root URL (/) and mounts the JSON API under /api/v1.

An operator signs in, selects a credential type, and shows a QR code. The holder scans the QR code with a wallet. The wallet sends a verifiable presentation to the credential verifier. A verifiable presentation is a signed set of credential claims that the holder chooses to share. The verifier app polls the transaction and shows the result.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart LR
    subgraph ACTORS["Operator and holder"]
        direction TB
        SP1[" "]
        OPE["Operator browser"]
        WAL["Wallet app"]
        SP1 ~~~ OPE
    end
    subgraph VA["Verifier app routes"]
        direction TB
        SP2[" "]
        SPA["SPA served from the root URL"]
        API["JSON API under /api/v1"]
        SP2 ~~~ SPA
    end
    subgraph CV["Credential verifier"]
        direction TB
        SP3[" "]
        OID["OpenID4VP service under /ewqwe_api"]
        SP3 ~~~ OID
    end
    OPE --> SPA
    OPE --> API
    API --> OID
    WAL --> OID
    OID --> WAL
    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;
    classDef cMgmt fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
    classDef cCtrl fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e;
    class OPE,WAL cExt;
    class SPA,API cMgmt;
    class OID cCtrl;
    style SP1 fill:none,stroke:none
    style SP2 fill:none,stroke:none
    style SP3 fill:none,stroke:none

Relation to the credential verifier

The verifier app runs inside the credential verifier process. The crate crates/ewqwe-credential-verifier-ui/ holds the routes, the user store, the locale files, and the SPA sources. The credential verifier:

  • mounts the app routes under the /api/v1 scope;
  • serves the SPA from the directory named by ui_dist_path;
  • shares its OpenID4VP service with the app, so that the app can start wallet transactions;
  • writes journal entries for successful verifications.

The app is disabled when the [verifier_ui] section is absent from the server configuration file. When the section is present, the app is enabled unless enabled = false. When the app is disabled, every /api/v1 route returns 404 and the server does not serve the SPA. See Credential verifier configuration.

HTTP routes

All routes use JSON request and response bodies. A POST or PUT request must send Content-Type: application/json. Sessions use an HttpOnly cookie named verifier_ui_session. In the table, {id} is a transaction identifier or a user identifier, depending on the route.

MethodPathAccessDescription
GET/api/v1/setup/statuspublicReport whether the first administrator exists.
POST/api/v1/setup/bootstrappublicCreate the first administrator account.
POST/api/v1/auth/loginpublicSign in and set the session cookie.
POST/api/v1/auth/logoutsessionEnd the session.
GET/api/v1/auth/mesessionReturn the signed-in user profile.
GET/api/v1/settingspublicReturn the app name, the logo URL, and the allowed types.
POST/api/v1/qr/generatesessionStart a transaction and return a QR code.
GET/api/v1/qr/{id}/statussessionReturn the status of a transaction.
GET/api/v1/admin/usersadminList user accounts.
POST/api/v1/admin/usersadminCreate a user account.
PUT/api/v1/admin/users/{id}adminUpdate a user account.
DELETE/api/v1/admin/users/{id}adminDelete a user account.
GET/api/v1/admin/journaladminList journal entries for the app users.
PUT/api/v1/admin/settingsadminUpdate the display settings.
GET/api/v1/i18npublicReturn locale strings for one language.
GET/publicServe the SPA entry page.
GET/assets/*publicServe the bundled JavaScript and CSS assets.
GET/logo.pngpublicServe the logo image.

Start a transaction

POST /api/v1/qr/generate accepts an optional body:

{
  "credential_type": "proof-of-age",
  "claims": ["age_over_18"]
}

The credential_type value is proof-of-age (the default), mdl, national-id, or france-identite-numerique. The claims array selects the claim names to request; an empty, absent, or null value uses the default claims of the credential type. The response contains the QR code and the identifiers that the app uses to poll the transaction:

{
  "transaction_id": "...",
  "qr_code_data_url": "data:image/svg+xml;base64,...",
  "authorization_request_uri": "av://?client_id=...&response_type=vp_token&...",
  "expires_in": 300
}

Poll a transaction

GET /api/v1/qr/{id}/status returns the transaction status:

{
  "status": "pending",
  "expires_in": 287
}
StatusMeaning
pendingThe wallet has not answered the request.
receivedThe wallet returned a presentation.
verifiedThe credential passed verification.
failedThe credential failed verification.
errorThe transaction failed with a processing error.
expiredThe transaction passed its time to live.

When the credential verifier verifies the presentation in process, a verified response also contains age_over_18 and verified_claims, and a failed response contains errors.

Configuration

The [verifier_ui] section of the server configuration file controls the app. A path resolves relative to the directory that contains the configuration file.

KeyTypeDefaultDescription
enabledbooleantrue when the section existsServe the app.
app_namestringVerifier AppDisplay name in the header.
logo_urlstringbuilt-in logoHTTPS URL or data: URL for the header logo.
qr_code_callback_urlstringpublic_root_urlBase URL for the wallet callback URIs.
allowed_credential_typesarray of stringsall typesCredential types that this server allows.
session_secretstringrandom key at startupSecret for signing session cookies.
ui_dist_pathstringnoneDirectory that holds the built SPA.
dbtablesqlite_memoryUser account store.

The allowed_credential_types value accepts proof-of-age, mdl, national-id, and france-identite-numerique. An empty list allows all types. The session_secret value must contain at least 8 characters. The server derives the cookie signing key from the value, so the same value keeps the sessions valid across restarts. When the value is absent, the server generates a random key, and every server restart ends all active sessions.

The qr_code_callback_url value overrides the public_root_url of the server. Set it only when the wallet callback must use a different URL from the rest of the server.

Database backends

The app stores user accounts in the backend named by the [verifier_ui.db] table.

BackendPersistenceExtra keysUse
sqlite_memorynonenoneDevelopment and testing.
sqlite_filefilepathA single instance with persistence.

Roles

RolePermissions
adminUser management, settings, journal, and QR codes.
verifierQR code generation and status polling.

The first account that setup/bootstrap creates is an administrator with is_superadmin = true. A superadmin cannot be deleted through the interface. A password must contain at least 12 characters.

Each user can also have a list of allowed credential types. An empty list means that the user inherits the server setting. A user restriction narrows the server setting; it never widens it.

Credential types and profiles

The credential type selects the OpenID4VP profile and the credential document type. The document type, also called the namespace, groups the claims of one credential format.

Credential typeProfileDocument type
proof-of-ageAnnex A (EU age verification)eu.europa.ec.av.1
mdlHAIPorg.iso.18013.5.1.mDL
national-idHAIPeu.europa.ec.eudi.pid.1
france-identite-numeriqueHAIPeu.europa.ec.eudi.pid.1

See Protocol modes and Credential types.

Languages

GET /api/v1/i18n?lang={code} returns the locale strings for the requested language. The app detects the browser language and uses the closest supported language. A user can override the language on the Settings page. The browser stores the preference under the key verifier_ui_lang.

CodeLanguage
enEnglish
deGerman
frFrench
itItalian
esSpanish
svSwedish
plPolish
csCzech
hrCroatian