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/v1scope; - 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.
| Method | Path | Access | Description |
|---|---|---|---|
| GET | /api/v1/setup/status | public | Report whether the first administrator exists. |
| POST | /api/v1/setup/bootstrap | public | Create the first administrator account. |
| POST | /api/v1/auth/login | public | Sign in and set the session cookie. |
| POST | /api/v1/auth/logout | session | End the session. |
| GET | /api/v1/auth/me | session | Return the signed-in user profile. |
| GET | /api/v1/settings | public | Return the app name, the logo URL, and the allowed types. |
| POST | /api/v1/qr/generate | session | Start a transaction and return a QR code. |
| GET | /api/v1/qr/{id}/status | session | Return the status of a transaction. |
| GET | /api/v1/admin/users | admin | List user accounts. |
| POST | /api/v1/admin/users | admin | Create a user account. |
| PUT | /api/v1/admin/users/{id} | admin | Update a user account. |
| DELETE | /api/v1/admin/users/{id} | admin | Delete a user account. |
| GET | /api/v1/admin/journal | admin | List journal entries for the app users. |
| PUT | /api/v1/admin/settings | admin | Update the display settings. |
| GET | /api/v1/i18n | public | Return locale strings for one language. |
| GET | / | public | Serve the SPA entry page. |
| GET | /assets/* | public | Serve the bundled JavaScript and CSS assets. |
| GET | /logo.png | public | Serve 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
}
| Status | Meaning |
|---|---|
pending | The wallet has not answered the request. |
received | The wallet returned a presentation. |
verified | The credential passed verification. |
failed | The credential failed verification. |
error | The transaction failed with a processing error. |
expired | The 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true when the section exists | Serve the app. |
app_name | string | Verifier App | Display name in the header. |
logo_url | string | built-in logo | HTTPS URL or data: URL for the header logo. |
qr_code_callback_url | string | public_root_url | Base URL for the wallet callback URIs. |
allowed_credential_types | array of strings | all types | Credential types that this server allows. |
session_secret | string | random key at startup | Secret for signing session cookies. |
ui_dist_path | string | none | Directory that holds the built SPA. |
db | table | sqlite_memory | User 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.
| Backend | Persistence | Extra keys | Use |
|---|---|---|---|
sqlite_memory | none | none | Development and testing. |
sqlite_file | file | path | A single instance with persistence. |
Roles
| Role | Permissions |
|---|---|
admin | User management, settings, journal, and QR codes. |
verifier | QR 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 type | Profile | Document type |
|---|---|---|
proof-of-age | Annex A (EU age verification) | eu.europa.ec.av.1 |
mdl | HAIP | org.iso.18013.5.1.mDL |
national-id | HAIP | eu.europa.ec.eudi.pid.1 |
france-identite-numerique | HAIP | eu.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.
| Code | Language |
|---|---|
en | English |
de | German |
fr | French |
it | Italian |
es | Spanish |
sv | Swedish |
pl | Polish |
cs | Czech |
hr | Croatian |