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.
The web redirection URL is configured in the tenant configuration parameter verifierUiUrl, or can be overridden using the verifierUiUrl URL parameter.
For starting a cross-device presentation flow, call this API with the required parameters to create a presentation request.
As a response, you get an object containing a requestId and a url.
Your application should now render the url from the response object as a QR code, or deep-link.
The requestId from the response object can be used to query the verification request status, using the API endpoint described here.
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 request status.
When the request is fulfilled, the response of the verification request status API, will contain a URI with the access_token parameter, which can be used to fetch the presentation result using the Verification result API.
Cross-device verification request status
GET /verifier-api/{tenantId}/verify/isVerified
Supported parameters:
Key
Description
Example
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/verify/isVerified?...
state
The request ID as returned by the presentXDevice API call
The application calls this API, after starting a cross-device presentation flow, using the request ID received in the response object for the state parameter of this API.
This API will return a status 404 Not found, while it is waiting for the cross-device request to be fulfilled.
When the request is fulfilled, it will return a status 200 OK with the redirection URL in the response body.
From the redirection URL, the application can parse the access_token parameter, to fetch the verification result.
Verification result
GET /verifier-api/<tenantID>/auth?access_token=abc123
Parameters
Key
Description
Example
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/auth?...
access_token
The access token, as returned in web redirection URL or cross-device verification response
access_token=abc123
The response of this request will be a verification result, like described in the section Example verification result section.
Verification callbacks
As seen in the first example, you can optionally set a callback:
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.
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.
