Management API

What this realm’s OID4VP Verifier asks a wallet for.

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/verifications

getVerifications

A verification’s outcome, or the verifications still open

With state: what the Verifier decided, with found: true: state, nonce, client_id, requested, dcql_query, received (whether a wallet has answered) and verdict (ok, checks, claims, disclosed, …, and presentationDigest, the SHA-256 of the presentation, which is never kept itself; null until it answers). A state this realm holds no record of is 404 with found: false (STS-VC-0042).

Without state: the realm’s open verifications, newest first — at most limit of total — each its state, what was asked (format, responseType, responseMode, byReference, clientId, requested), expiresAt, and what was decided (received, ok, decidedAt, the disclosed claim NAMES, failedChecks, a wallet’s error). A wallet SIGN-IN is not listed: it is a person signing in, not a verification an administrator asked for. The Verifier request tab draws this list.

Mirrors GET /admin/vc on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
state query string   The state POST /verifications/start answered.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: One outcome, or the open verifications.

Member Type Required What it is
client_id string    
dcql_query object    
dcql_query.credential_sets list    
dcql_query.credential_sets[].options list    
dcql_query.credential_sets[].options[] list    
dcql_query.credential_sets[].options[][] string    
dcql_query.credential_sets[].required boolean    
dcql_query.credentials list    
dcql_query.credentials[].claims list    
dcql_query.credentials[].claims[].path list    
dcql_query.credentials[].claims[].path[] string    
dcql_query.credentials[].format string    
dcql_query.credentials[].id string    
dcql_query.credentials[].meta object    
dcql_query.credentials[].meta.doctype_value string    
dcql_query.credentials[].meta.type_values list    
dcql_query.credentials[].meta.type_values[] list, or string    
dcql_query.credentials[].meta.type_values[][] string    
dcql_query.credentials[].meta.vct_values list    
dcql_query.credentials[].meta.vct_values[] string    
dcql_query.credentials[].require_cryptographic_holder_binding boolean    
found boolean    
limit integer    
nonce string    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
received boolean    
requested list    
requested[] string    
state string    
total integer    
verdict object    
verdict.at string    
verdict.checks list    
verdict.checks[].detail list, or string, or number, or boolean, or null    
verdict.checks[].detail[] string, or number, or boolean    
verdict.checks[].name string    
verdict.checks[].ok boolean    
verdict.claims any JSON   What a holder’s wallet disclosed from a credential, which may be another issuer’s: its names and values are the presentation’s, not this service’s. What a holder’s wallet disclosed from a credential, which may be another issuer’s: its names and values are the presentation’s, not this service’s.
verdict.disclosed list    
verdict.disclosed[] list, or string, or number, or boolean, or null    
verdict.disclosed[][] string, or number, or boolean    
verdict.error string    
verdict.errorDescription string    
verdict.extraDisclosed list    
verdict.extraDisclosed[] list, or string, or number, or boolean, or null    
verdict.extraDisclosed[][] string, or number, or boolean    
verdict.format string    
verdict.ok boolean    
verdict.presentationDigest list, or string, or number, or boolean, or null    
verdict.presentationDigest[] string, or number, or boolean    
verdict.refused boolean    
verdict.requested list    
verdict.requested[] string    
verdict.selfIssued object    
verdict.selfIssued.claims any JSON   What a holder’s wallet disclosed from a credential, which may be another issuer’s: its names and values are the presentation’s, not this service’s. What a holder’s wallet disclosed from a credential, which may be another issuer’s: its names and values are the presentation’s, not this service’s.
verdict.selfIssued.subject list, or string, or number, or boolean, or null    
verdict.selfIssued.subject[] string, or number, or boolean    
verdict.sub list, or string, or number, or boolean, or null    
verdict.sub[] string, or number, or boolean    
verdict.vct list, or string, or number, or boolean, or null    
verdict.vct[] string, or number, or boolean    
verifications list    
verifications[].byReference boolean    
verifications[].claims list    
verifications[].claims[] string    
verifications[].clientId string    
verifications[].decidedAt string, or null    
verifications[].error string    
verifications[].expiresAt string    
verifications[].failedChecks list    
verifications[].failedChecks[] string    
verifications[].format string    
verifications[].ok boolean, or null    
verifications[].received boolean    
verifications[].requested list    
verifications[].requested[] string    
verifications[].responseMode string    
verifications[].responseType string    
verifications[].state string    

404: The answer.

Member Type Required What it is
errors list    
errors[] string    
found boolean    
ok boolean    
state string    

POST /admin-api/verifications/start

startVerification

Start an OpenID4VP verification: build a request for a wallet

Builds a presentation request — the one door a verification starts at since #594 — and answers how a wallet is handed it: walletUrl (what a same-device start redirects to: the web wallet wallet named or oid4vp.walletUrl configures, with the request on its query, or — with neither, the default — the same as requestUri), requestUri (the request under the scheme a wallet app registers for: openid4vp://, HAIP’s haip-vp:// where oid4vp.walletInvocation says so, or SIOPv2’s siopv2:// for an ID Token alone; what a cross-device QR code carries), wallet (the address or scheme before the query), query itself, and — by reference — the request_uri the wallet fetches the signed Request Object from. state names it; GET /verifications?state= reads its outcome.

The body names what the page’s query names, every member optional: format (a format id, GET /verifier-request lists them; the configured default when absent), by (value or reference), client_id_prefix (a signed request’s Client Identifier Prefix — naming one asks for a request by reference), response_type, response_mode, mode (same-device or cross-device, which only says which of the two addresses a caller means to use) and wallet (held to oid4vp.walletUrl and oid4vp.allowedWalletUrls wherever only registered addresses are accepted).

redirect_uri (#594) is the caller’s own page the Response Endpoint sends the wallet to once it has answered (OpenID4VP 1.0 section 8.2). Wherever only registered addresses are accepted it must be one of the CALLING CLIENT’s registered redirect URIs, matched whole (400, STS-VC-0123); left off, the Response Endpoint answers no redirect_uri — what a wallet on another device wants.

What the request ASKS FOR is the Verifier request’s configuration (/verifier-request), frozen onto the transaction now. Refused as the page refuses: 400 for what the request names wrongly (STS-VC-0032) and for a wallet this realm will not send a request to (STS-VC-0033), and 500 with the builder’s own code where no request can be built — a Verifier Attestation this realm cannot use (STS-VC-0092), an x509 Client Identifier with nothing to certify (STS-VC-0110 to STS-VC-0113). Answered in every mode: this is an administrator asking.

Mirrors POST /admin/vc#vc-tab-verifier-request on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body (optional)

Member Type Required What it is
by one of value, reference    
client_id_prefix one of pre-registered, decentralized_identifier, verifier_attestation, openid_federation, x509_san_dns, x509_hash    
format string   A format id: dc+sd-jwt, jwt_vc_json, ldp_vc, mso_mdoc. Not a closed set here, as on /verifier-request/format: a form-encoded + arrives as a space and is put back, and the Verifier refuses anything else by name.
mode one of same-device, cross-device    
redirect_uri string   The caller’s page the wallet is sent to once the Verifier has answered (#594); a registered redirect URI of the calling client wherever only registered addresses are accepted.
response_mode one of direct_post, direct_post.jwt, form_post    
response_type one of vp_token, id_token, vp_token id_token    
wallet string   A web wallet to send the holder to, if not oid4vp.walletUrl or a wallet app (the default).

200: state, walletUrl, requestUri, query, the request_uri by reference, and what was asked: ok, message, state, nonce, mode, format, responseType, responseMode, byReference, clientId, requested, dcql_query, expiresAt, wallet, walletUrl, requestUri, query, redirectUri (‘’ for none) and, by reference, request_uri.

Member Type Required What it is
byReference boolean    
clientId string    
dcql_query object    
dcql_query.credential_sets list    
dcql_query.credential_sets[].options list    
dcql_query.credential_sets[].options[] list    
dcql_query.credential_sets[].options[][] string    
dcql_query.credential_sets[].required boolean    
dcql_query.credentials list    
dcql_query.credentials[].claims list    
dcql_query.credentials[].claims[].path list    
dcql_query.credentials[].claims[].path[] string    
dcql_query.credentials[].format string    
dcql_query.credentials[].id string    
dcql_query.credentials[].meta object    
dcql_query.credentials[].meta.doctype_value string    
dcql_query.credentials[].meta.type_values list    
dcql_query.credentials[].meta.type_values[] list, or string    
dcql_query.credentials[].meta.type_values[][] string    
dcql_query.credentials[].meta.vct_values list    
dcql_query.credentials[].meta.vct_values[] string    
dcql_query.credentials[].require_cryptographic_holder_binding boolean    
errors list    
errors[] string    
expiresAt string    
format string    
message string    
mode string    
nonce string    
ok boolean yes  
query string    
redirectUri string, or null    
requestUri string    
request_uri string    
requested list    
requested[] string    
responseMode string    
responseType string    
state string    
wallet string    
walletUrl string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
byReference boolean    
clientId string    
dcql_query object    
dcql_query.credential_sets list    
dcql_query.credential_sets[].options list    
dcql_query.credential_sets[].options[] list    
dcql_query.credential_sets[].options[][] string    
dcql_query.credential_sets[].required boolean    
dcql_query.credentials list    
dcql_query.credentials[].claims list    
dcql_query.credentials[].claims[].path list    
dcql_query.credentials[].claims[].path[] string    
dcql_query.credentials[].format string    
dcql_query.credentials[].id string    
dcql_query.credentials[].meta object    
dcql_query.credentials[].meta.doctype_value string    
dcql_query.credentials[].meta.type_values list    
dcql_query.credentials[].meta.type_values[] list, or string    
dcql_query.credentials[].meta.type_values[][] string    
dcql_query.credentials[].meta.vct_values list    
dcql_query.credentials[].meta.vct_values[] string    
dcql_query.credentials[].require_cryptographic_holder_binding boolean    
errors list    
errors[] string    
expiresAt string    
format string    
message string    
mode string    
nonce string    
ok boolean yes  
query string    
redirectUri string, or null    
requestUri string    
request_uri string    
requested list    
requested[] string    
responseMode string    
responseType string    
state string    
wallet string    
walletUrl string    

GET /admin-api/verifier-request

getVerifierRequest

What this realm’s OID4VP Verifier asks a wallet for

The claims, the credential format, and the dcql_query they build — from the function that builds the real one, so this is the next Authorization Request rather than a description of it.

Each catalogue row also says whether the ISSUER currently mints that claim. The two settings are deliberately separate and their disagreeing is a state to report rather than one to prevent: a Verifier asking for a claim nothing here issues is the only way to exercise what a wallet does with a request it cannot satisfy.

recentVerifications (#587) is GET /verifications without a state — the open verifications and their outcomes the tab lists under its Start a verification form.

Mirrors GET /admin/vc on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The request as it now stands.

Member Type Required What it is
catalogue list    
catalogue[].attributes list    
catalogue[].attributes[].ldap string    
catalogue[].attributes[].schema string    
catalogue[].claim string    
catalogue[].issued object    
catalogue[].issued.carried list    
catalogue[].issued.carried[] string    
catalogue[].issued.known boolean    
catalogue[].issued.missing list    
catalogue[].issued.missing[] string    
catalogue[].label string    
catalogue[].ldpTerms list    
catalogue[].ldpTerms[] string    
catalogue[].nested boolean    
catalogue[].paths list    
catalogue[].paths[] list    
catalogue[].paths[][] string    
catalogue[].requested boolean    
dcqlQuery object    
dcqlQuery.credential_sets list    
dcqlQuery.credential_sets[].options list    
dcqlQuery.credential_sets[].options[] list    
dcqlQuery.credential_sets[].options[][] string    
dcqlQuery.credential_sets[].required boolean    
dcqlQuery.credentials list    
dcqlQuery.credentials[].claims list    
dcqlQuery.credentials[].claims[].path list    
dcqlQuery.credentials[].claims[].path[] string    
dcqlQuery.credentials[].format string    
dcqlQuery.credentials[].id string    
dcqlQuery.credentials[].meta object    
dcqlQuery.credentials[].meta.doctype_value string    
dcqlQuery.credentials[].meta.type_values list    
dcqlQuery.credentials[].meta.type_values[] list, or string    
dcqlQuery.credentials[].meta.type_values[][] string    
dcqlQuery.credentials[].meta.vct_values list    
dcqlQuery.credentials[].meta.vct_values[] string    
dcqlQuery.credentials[].require_cryptographic_holder_binding boolean    
defaults list    
defaults[] string    
extras list    
extras[].claim string    
extras[].paths list    
extras[].paths[] list    
extras[].paths[][] string    
format string    
formats list    
formats[].configurations list    
formats[].configurations[] string    
formats[].holderBinding string    
formats[].id string    
formats[].identifiedBy string    
formats[].identifier list, or string    
formats[].identifier[] string    
formats[].identifierText string    
formats[].label string    
formats[].selectiveDisclosure string    
formats[].what string    
ldpOmitted list    
ldpOmitted[] string    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
recentVerifications object    
recentVerifications.limit integer    
recentVerifications.total integer    
recentVerifications.verifications list    
recentVerifications.verifications[].byReference boolean    
recentVerifications.verifications[].claims list    
recentVerifications.verifications[].claims[] string    
recentVerifications.verifications[].clientId string    
recentVerifications.verifications[].decidedAt string, or null    
recentVerifications.verifications[].error string    
recentVerifications.verifications[].expiresAt string    
recentVerifications.verifications[].failedChecks list    
recentVerifications.verifications[].failedChecks[] string    
recentVerifications.verifications[].format string    
recentVerifications.verifications[].ok boolean, or null    
recentVerifications.verifications[].received boolean    
recentVerifications.verifications[].requested list    
recentVerifications.verifications[].requested[] string    
recentVerifications.verifications[].responseMode string    
recentVerifications.verifications[].responseType string    
recentVerifications.verifications[].state string    
requested list    
requested[] string    
startChoices object    
startChoices.by list    
startChoices.by[] string    
startChoices.client_id_prefix list    
startChoices.client_id_prefix[] string    
startChoices.format list    
startChoices.format[] string    
startChoices.mode list    
startChoices.mode[] string    
startChoices.response_mode list    
startChoices.response_mode[] string    
startChoices.response_type list    
startChoices.response_type[] string    

POST /admin-api/verifier-request/add

addRequestedClaim

Ask for one more claim

A claim NOT in the catalogue is accepted, and is the point rather than a loose end: nothing here issues it, so it is the only way to exercise what a wallet does with a request it cannot satisfy. The reply says so, and the Verifier will then refuse the presentation on the “Requested claims” check and name it.

Mirrors POST /admin/vc#vc-tab-verifier-request on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
(the answer) any JSON    

200: What is requested now.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

POST /admin-api/verifier-request/defaults

resetRequestedClaims

Back to what this process started with

OID4VP_CLAIMS where that was set in the environment, and given_name, family_name where it was not.

Mirrors POST /admin/vc#vc-tab-verifier-request on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body (optional)

An empty object.

200: The startup request.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

POST /admin-api/verifier-request/format

setRequestFormat

Set the credential format a request asks in

Applies to a request that does not name a format itself; the three format links on the Verifier page name one explicitly and are unaffected.

The DCQL PATH DIFFERS BY FORMAT and the reply shows it: top level for dc+sd-jwt, under credentialSubject for jwt_vc_json, and under the vendored JSON-LD context’s own term for ldp_vc — which cannot carry every claim at all.

Mirrors POST /admin/vc#vc-tab-verifier-request on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
format string yes A format id. GET /admin-api/verifier-request lists them under formats.
name string   An alias for claim; vpConfigAction() reads body.claim \|\| body.name, so both spellings have always worked and only one was published.

200: The format now in force.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

POST /admin-api/verifier-request/remove

removeRequestedClaim

Stop asking for one claim

A claim that is not being asked for is refused rather than treated as done.

Mirrors POST /admin/vc#vc-tab-verifier-request on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
(the answer) any JSON    

200: What is requested now.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

POST /admin-api/verifier-request/select

selectRequestedClaims

Set the whole list of requested claims

Reaches the wire as the claims member of the next Authorization Request’s dcql_query.

An EMPTY array is a legitimate call and not an empty form: DCQL reads an absent claims member as the WHOLE credential, so requesting nothing asks the wallet for everything — the opposite of what selective disclosure is for, which is exactly why being able to ask for it matters.

The claims a request asks for are FROZEN onto the transaction when it is built, so a change here never re-judges a presentation already in flight.

Mirrors POST /admin/vc#vc-tab-verifier-request on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
claims list yes Top-level claim names. A credential carries one Disclosure per top-level claim, so address is one unit however many attributes feed it.
claims[] string    

200: What is requested now, and what changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
added list    
added[] string    
errors list    
errors[] string    
format string    
message string    
ok boolean yes  
removed list    
removed[] string    
requested list    
requested[] string