There are 3 ways to integrate the verification flows into your application:
Same-device (web-based) flow
Cross-device flow (with QR code)
Via webhooks (callback)
In all cases, first make sure you have your tenant configured with all the verification policies, etc. that fit your requirements.
Then start the presentation flow, using the methods described below.
Same device flow
GET /verifier-api/<tenantId>/present?walletId=walt.id&vcType=VerifiableId
Supported parameters:
Key
Description
Example
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/present?...
walletId
Wallet ID as configured in the tenant configuration
walletId=walt.id
vcType
Credential type that should be requested in the presentation request. Can be specified multiple times
vcType=VerifiableId&vcType=Europass
pdByReference
pdByReference=false
verifierUiUrl
verifierUiUrl=https://myservice.example.com/verification/callback/, will be called like: https://myservice.example.com/verification/callback/success/?access_token=abc123
(a local wallet at localhost was configured in this example case)
By telling the wallet what vcType is required, it will usually filter the list of credentials in the user UI to only display relevant credentials of the specified type.
In the same-device flow the browser gets navigated to this API URL, with the given parameters
The walletkit redirects to the wallet and on completion, the walletkit redirects the browser back to the application.
When setting a callback, the Wallet Kit will then call this callback as webhook when the user shares a credential (in the walt.id demo wallet: actually clicks "Share credentials").
Before answering the user, the Wallet Kit will send out an HTTP Post request using the parameters described below.
When the callback answers HTTP statuses
Statuses:
OK (200),
NoContent (201),
or Accepted (202)
the Wallet Kit will mark the callback as accepted and continue its normal operation.
When the callback answers HTTP statuses
Statuses:
MovedPermanently (301),
Found (302),
TemporaryRedirect (307),
or PermanentRedirect (308)
the Wallet Kit will abort its operation and redirect the user (using the Location header) to the Location specified by the callback.
This is useful for redirecting to pages based on what credentials the user shares or change depending on the data of the credentials.
When the callback answers HTTP statuses
Statuses:
Unauthorized (401),
or Forbidden (403)
the Wallet Kit will invalidate the status and set overallValid to false, even if the selected VerificationPolicys would result in an overallValid = true.
Callback data to work with
When you set up your webhook to listen for such a Wallet Kit callback, you have a variety of data to work with:
state: (UUID) ID of the verification session
subject: (DID) DID of the user that created the shared presentation
auth_token: (JWT[Subject]) Signed representation of subject = DID
vps: (List[VPVerificationResult])
VPVerificationResult:
vp: (JWT) Signed representation of the Verifiable Presentation
Including DIDs, issuance dates (attribute iat, nbf), etc...
and obviously the actual Verifiable Credential (in attribute vc)
vcs: (List[JWT])
Signed Verifiable Credentials sourced from the Verifiable Presentation (VC in attribute vc, issuance date iatnbf, Subject DID sub, ...)
verification_result: (VerificationResult)
valid: Boolean
overall valid state
policyResults: Map[Policy -> Boolean]
e.g. policyResults={SignaturePolicy=true, ChallengePolicy=true, PresentationDefinitionPolicy=true}
Example JSON body you'll receive with a webhook callback for the VerifiableID demo
If true, the presentation definition will be passed as a URI in the presentation request (see ), otherwise a full PD object is included in the parameter.
Web redirection URL, on which the verification result will be received. The browser will be navigated to this URL with the sub-path /success, containing an access_token parameter, which can be used to obtain the verification result, overrides the configuration parameter in the tenant configuration
Webhook to actively callback with the verification result (see also ), the URL needs to be configured as allowed webhook in the tenant configuration.
The web redirection URL is configured in the tenant configuration parameter , or can be overridden using the verifierUiUrl URL parameter.
The verifierUiUrl is called with the sub-path /success and an access_token parameter, which can be used to .
Use the access token to retrieve the verification result from the walletkit like described in .
If true, the presentation definition will be passed as a URI in the presentation request (see ), otherwise a full PD object is included in the parameter.
The requestId from the response object can be used to query the verification request status, using the API endpoint described .
The wallet can scan the rendered QR code and parse the presentation request. Eventually it will post the presentation response to the walletkit backend, which will update the .
When the request is fulfilled, the response of the API, will contain a URI with the access_token parameter, which can be used to fetch the presentation result using the API.
The application calls this API, after starting a , using the request ID received in the response object for the state parameter of this API.
From the redirection URL, the application can parse the access_token parameter, to fetch the .
The response of this request will be a verification result, like described in the section section.
