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

Credential verifier HTTP API

The credential verifier exposes an HTTP API over TLS. This page documents every endpoint, the request body, the response body, the status codes, and the error cases.

Base path and authentication

Every endpoint starts with /ewqwe_api. The server serves two further paths outside that prefix: GET /version and the verifier app single-page application at /.

The endpoints fall into three authentication classes.

ClassEndpointsClient certificate
Relying party/ewqwe_api/verify, /ewqwe_api/openid4vp/init, /ewqwe_api/openid4vp/status/{id}, /ewqwe_api/journal/*, /ewqwe_api/.well-known/issuer_certsRequired
Wallet/ewqwe_api/openid4vp/direct_post, /ewqwe_api/openid4vp/request/{id}, /ewqwe_api/openid4vp/.well-known/jwks.jsonNot required
Public/versionNot required

A relying-party endpoint requires a verified client certificate. The server uses the certificate Common Name (CN) as the authenticated username. See TLS and mutual TLS for the certificate requirements.

Request limits

SettingValue
Maximum request payload1,000,000 bytes
Maximum JSON payload1,000,000 bytes
Keep-alive timeout120 seconds
Client request timeout10 seconds

Error responses

The server returns two error-body shapes.

The credential verifier core returns the error message as a JSON string with these status codes.

ConditionStatusBody
Invalid request parameter400JSON string error message
Missing or failed authentication401JSON string error message
Any other failure500JSON string error message

The OpenID4VP endpoints return a JSON object with an error field and these status codes.

ConditionStatusBody
Unknown transaction404{ "error": "<message>" }
Expired transaction410{ "error": "<message>", "status": "expired" }
Invalid request400{ "error": "<message>" }
Cryptographic failure500{ "error": "Internal crypto error" }
Configuration failure500{ "error": "credential verifier configuration: <message>" }
Internal failure500{ "error": "Internal server error" }

POST /ewqwe_api/verify

Verifies a verifiable presentation (VP) token and returns a signed attestation. This endpoint requires a client certificate.

Request body

The request body is a JSON object.

FieldTypeRequiredDescription
vp_tokenstringYesThe VP token from the wallet.
statestringNoTransaction state used to look up the stored nonce and request context.
client_idstringNoRelying-party identifier used as the attestation audience.
presentation_submissionobjectNoPresentation submission. Usually absent for DCQL-based responses.

The vp_token value is a JSON string. The server accepts three presentation shapes:

  • A DCQL object whose keys are credential query identifiers and whose values are arrays of presentations.
  • An SD-JWT VC compact serialization, which contains the ~ separator.
  • A base64url-encoded mDoc DeviceResponse (CBOR).

The state field locates a stored OpenID4VP transaction. The server reads the nonce and the request context from that transaction and never from the request body. For mDoc verification the state field is required, because the server rebuilds the OpenID4VP handover from the stored context.

The client_id field is required when no stored transaction exists, for example in the same-device Digital Credentials API flow. When a stored transaction exists, the server rejects a client_id value that differs from the transaction value.

Response body

The response body is a JSON object. The server returns this shape with status 200 for both a successful and a failed verification.

FieldTypePresentDescription
successbooleanAlwaysThe verification result.
messagestringAlwaysHuman-readable result message.
attestationstringAlwaysSigned attestation JWT. See Attestations.
verification_detailsobjectAlwaysVerification breakdown. See below.
errorsarrayOn failureHuman-readable failure reasons.

The verification_details object holds three boolean fields.

FieldTypeDescription
signature_validbooleanThe presentation signature is valid.
not_expiredbooleanThe credential is within its validity period.
issuer_trustedbooleanThe issuer chain terminates at a trusted CA.

Status codes

StatusCondition
200The server processed the presentation. Check success for the result.
400The vp_token is malformed, the client_id disagrees with the transaction, the mDoc state is missing, or an mDoc check fails.
401No authenticated user is present.
500An internal failure occurred, for example a journal append failure.

Example

{
  "vp_token": "{\"proof_of_age\":[\"o2d2ZXJzaW9u...\"]}",
  "state": "f7c1a2e0-5b3d-4a9c-9f21-8d2e6b0a1c34",
  "client_id": "x509_san_dns:rp.example.com"
}
{
  "success": true,
  "message": "Credential verified successfully",
  "verification_details": {
    "signature_valid": true,
    "not_expired": true,
    "issuer_trusted": true
  },
  "attestation": "eyJhbGciOiJFUzI1NiIsImtpZCI6..."
}

POST /ewqwe_api/openid4vp/init

Starts a new OpenID4VP transaction. This endpoint requires a client certificate.

Request body

The request body is a JSON object.

FieldTypeRequiredDescription
dcql_queryobjectNoDigital Credentials Query Language query. A default age query is used when omitted.
noncestringNoRequest nonce. The server generates one when omitted.
statestringNoClient state value. The server generates one when omitted.
profilestringNoProtocol profile, haip or annex-a.
credential_typestringNoCredential shorthand: mdl, national-id, proof-of-age, or france-identite-numerique.
client_metadataobjectNoRelying-party metadata shown by the wallet.
transaction_dataarrayNoBase64url-encoded transaction data entries.

The server builds the response_uri and the request_uri from public_root_url, or from the incoming request when public_root_url is not set. See Credential verifier configuration.

Response body

FieldTypePresentDescription
transaction_idstringAlwaysIdentifier used for later status polling.
client_idstringAlwaysConstructed client identifier.
client_id_schemestringAlwaysClient identifier scheme, for example x509_san_dns.
request_uristringAlwaysURI where the wallet fetches the authorization request.
authorization_request_uristringAlwaysFull authorization request URI for a QR code or deep link.
expires_inintegerAlwaysSeconds until the transaction expires.
profilestringAlwaysSelected protocol profile.
qr_code_data_urlstringCross-deviceQR code as an image/svg+xml data URL.

Status codes

StatusCondition
200The transaction was created.
400The request body is invalid.
401No authenticated user is present.
500A configuration or internal failure occurred.

POST /ewqwe_api/openid4vp/direct_post

Receives the wallet authorization response. This endpoint does not require a client certificate.

Request body

The server accepts two content types.

For application/x-www-form-urlencoded, the server reads these form parameters.

ParameterRequiredDescription
vp_tokenFor a plain responseThe VP token.
stateFor a plain responseTransaction state echoed by the wallet.
presentation_submissionNoPresentation submission string.
responseFor a JWE response (direct_post.jwt)Encrypted authorization response.
errorFor a wallet error responseOpenID4VP error code.
error_descriptionNoHuman-readable error description.

For application/json, the server reads the same fields as a JSON object.

When the wallet sends an error parameter, the server records a wallet error and does not expect a VP token.

Response body

On success the server returns status 200, the content type application/json, and an empty JSON object {}.

Status codes

StatusCondition
200The response was stored.
400The body is malformed or the state is unknown.
404No transaction matches the state.
410The transaction has expired.
500A cryptographic, configuration, or internal failure occurred.

GET and POST /ewqwe_api/openid4vp/request/

Returns the authorization request for a transaction. The wallet fetches this URI from the request_uri value. This endpoint does not require a client certificate.

Path parameter

ParameterTypeDescription
idstringThe transaction identifier.

Response body

The response body is either a signed JAR (JWT-secured authorization request) or a plain JSON object, depending on the profile.

ProfileContent typeBody
HAIPapplication/oauth-authz-req+jwtSigned JAR JWT.
Annex Aapplication/jsonPlain authorization request JSON.

Status codes

StatusCondition
200The request is returned.
404The transaction is unknown.
410The transaction has expired.
500An internal failure occurred.

GET /ewqwe_api/openid4vp/status/

Returns the status of a transaction. This endpoint requires a client certificate.

Path parameter

ParameterTypeDescription
idstringThe transaction identifier.

Response body

FieldTypePresentDescription
statusstringAlwaysOne of pending, received, verified, error, expired.
expires_inintegerWhen pendingSeconds until expiry.
authorization_responseobjectWhen receivedThe wallet authorization response.
noncestringWhen receivedNonce from the original authorization request.
transaction_dataarrayWhen receivedTransaction data from the original request.
wallet_errorobjectWhen the wallet returned an errorWallet error code and description.
error_messagestringOn a server errorServer error description.

The authorization_response object holds vp_token, state, and an optional presentation_submission.

The status value has the meanings below.

ValueMeaning
pendingWaiting for the wallet response.
receivedWallet response received, not yet verified.
verifiedCredential verified successfully.
errorVerification or processing failed.
expiredTransaction TTL exceeded.

Status codes

StatusCondition
200The status is returned.
404The transaction is unknown.
410The transaction has expired.
500An internal failure occurred.

GET /ewqwe_api/openid4vp/.well-known/jwks.json

Returns the public JSON Web Key Set (JWKS). This endpoint does not require a client certificate.

Response body

The response content type is application/jwk-set+json. The body holds a keys array with up to two groups of keys.

KeyPresentPurpose
JAR signing keyHAIP profileLets the wallet verify the signed authorization request.
Attestation verification keyAlwaysLets the relying party verify a signed attestation JWT.

The attestation verification key is an EC P-256 key with alg set to ES256. The key carries the fields kty, crv, use, alg, kid, x, y, and x5c. The kid value is the base64url (no padding) SHA-256 fingerprint of the certificate. The same kid appears in the header of every attestation JWT.

Status codes

StatusCondition
200The key set is returned.

GET /ewqwe_api/.well-known/issuer_certs

Returns the trusted credential issuer CA certificates. This endpoint requires a client certificate.

Query parameters

ParameterTypeDefaultDescription
cert_pembooleanfalseInclude the PEM encoding of each certificate.

Response body

FieldTypeDescription
loadedbooleanThe server loaded at least one CA.
countintegerNumber of trusted CA certificates.
certsarrayOne object per CA certificate.

Each entry in certs holds these fields.

FieldTypePresentDescription
subjectstringAlwaysCertificate Subject Common Name.
issuerstringAlwaysCertificate Issuer Common Name.
not_beforestringAlwaysValidity start.
not_afterstringAlwaysValidity end.
cert_pemstringWhen cert_pem=trueCertificate in PEM encoding.

Status codes

StatusCondition
200The certificate list is returned.
401No authenticated user is present.

Journal endpoints

The journal endpoints return the append-only verification journal of the authenticated user. Each endpoint requires a client certificate, and the authenticated username must match the {username} path parameter. When the journal is disabled, the journal store is absent and a request to these paths returns an internal server error.

See the Verification journal page for the entry schema.

GET /ewqwe_api/journal/{username}/entries

Returns the recent journal entries of the user, newest first, as human-readable views.

Query parameterTypeDefaultDescription
limitinteger20Maximum entries. The server caps the value at 1000.
beforestring—Return entries created strictly before this RFC 3339 timestamp.
afterstring—Return entries created strictly after this RFC 3339 timestamp.

Each entry holds these fields.

FieldTypeDescription
created_atstringEntry creation time in RFC 3339 format.
qrcode_app_user_emailstringEmail of the verifier app user, when present.
successbooleanWhether the verification succeeded.
claimsobjectFlattened credential claims.

GET /ewqwe_api/journal/{username}/verify

Recomputes every entry hash from the first entry and checks the chain.

FieldTypeDescription
usernamestringThe journal owner.
validbooleantrue when every hash matches.
entries_verifiedintegerNumber of entries checked.
first_entry_hashstringHash of the first entry, when present.
last_entry_hashstringHash of the current head, when present.
errorstringReason when valid is false.

GET /ewqwe_api/journal/{username}/download

Returns the matching journal entries as a JSON file. The server sets the header Content-Disposition: attachment with the file name journal_{username}.json.

Query parameterTypeDefaultDescription
beforestring—Return entries created strictly before this RFC 3339 timestamp.
afterstring—Return entries created strictly after this RFC 3339 timestamp.
limitintegerAllMaximum entries.

Unlike the /entries endpoint, the download returns the full journal entry, including the chain hash fields.

Journal status codes

StatusCondition
200The result is returned.
401No authenticated user is present, or the username does not match.
500The journal is disabled, or a storage failure occurred.

GET /version

Returns the server version. This endpoint does not require a client certificate.

Response body

FieldTypeDescription
versionstringThe compiled credential verifier version.
{
  "version": "0.1.0"
}

Status codes

StatusCondition
200The version is returned.