Since mid-Jan Q1/23 the Wallet Kit extended it's multi-issuer configurability to a complete multi-tenancy supported system.
All API endpoints for issuer configuration have the option for setting a tenantId.
The default tenantId is "default".
Creating a DID for a tenant
POST /issuer-api/{tenantId}/config/did/create
POST this JSON body to the specified URL:
Method being one of: [ key, web, ebsi, iota, cheqd, jwk ]. Only the method is required. All "didWeb" prefixed options are only needed for creating a did:web.
(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.
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
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
(Empty values that are not set [= null] are omitted for this example, e.g. no expirationDate was set, thus you'll receive "expirationDate": null)
Credential Issuance
Issuance is very simple, in fact, you only need to call a single HTTP POST endpoint:
Issue Credential
POST /issuer-api/{tenantId}/credentials/issuance/request
Wallet
When issuing a credential, you will have to pre-select what type of wallet shall be used.
There are three types of wallets:
Mobile wallets:
Cross device flow: User uses another device (desktop pc, laptop) than where their wallet is installed (smartphone).
In this case, you will use the virtual wallet "x-device", which creates an "openid-initiate-issuance://..." URL.
Web wallets:
Same device flow: User uses the same device that their wallet is installed on.
In this case, you will have to additionally ask what web wallet the user is using (if you aren't forcing them to use your or an specific web wallet).
e.g. "walt.id", which creates an "..." URL.
App wallets
Theoretically same device flow, but also uses the virtual wallet "x-device" for creating an "openid-initiate-issuance://..." URL.
In the default configuration you can use the wallet "walt.id" (), or the virtual wallet "x-device" for the cross device flow ("openid-initiate-issuance://...").
The selected walletId is the id configured in the mappings seen in wallet_kit-configuration.m
Key
Description
Example
Key
Description
Example
Key
Description
Example
Answers with a redirect (header "Location") to the issuance URL, e.g.
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
If true, the presentation definition will be passed as a URI in the presentation request (see presentation_definition_uri), otherwise a full PD object is included in the presentation_definition parameter.
pdByReference=false
verifierUiUrl
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 verifierUiUrl configuration parameter in the tenant configuration
verifierUiUrl=https://myservice.example.com/verification/callback/, will be called like: https://myservice.example.com/verification/callback/success/?access_token=abc123
verificationCallbackUrl
Webhook to actively callback with the verification result (see also Verification callbacks), the URL needs to be configured as allowed webhook in the tenant configuration.
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/presentXDevice?...
vcType
Credential type that should be requested in the presentation request. Can be specified multiple times
vcType=VerifiableId&vcType=Europass
pdByReference
If true, the presentation definition will be passed as a URI in the presentation request (see presentation_definition_uri), otherwise a full PD object is included in the presentation_definition parameter.
pdByReference=false
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
state=req123
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