#Receive and Store mDL Via OID4VCI

There are several methods by which a user can receive a mDL into their wallet, and all are supported by the wallet API:

1. User may receive a direct link, which opens the wallet and prompts credential acceptance.
2. A website may display a QR code for the user to scan and accept the credential.
3. The user may manually input an offer URL string into a text field.

Irrespective of the chosen method, these are just different ways of receiving, parsing and fulfilling a request URL.

#Credential Offer URL

A credential offer URL is a standardized method, as per the OID4VCI specification, to communicate the issuance of credentials between issuer and wallet. This URL can take various forms, such as a QR code or a link, and generally begins with openid-credential-offer:// or haip://.

Example Offer URL

openid-credential-offer://issuer.portal.walt.id/?credential_offer=<credential_offer>

Within the URL, a query parameter credential_offer provides the actual offer.

Example of a Credential Offer Object

{
  "credential_issuer": "http://localhost:7002",
  // This is the URL of the issuer of the credential(s)
  "credential_configuration_ids": [
    // This array contains details about the types of credentials being offered
    "org.iso.18013.5.1.mDL"
  ],
  "grants": {
    // Specifies how the credentials can be obtained
    "authorization_code": {
      "issuer_state": "7a76d97f-aa99-45ee-a130-fb6674f699a4"
      // Contains an issuer_state, a unique identifier for the grant
    },
    "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
      // Provides details for a pre-authorized code grant type,
      //including the actual pre-authorized_code 
      "pre-authorized_code": "eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiI3YTc2ZDk3Zi1hYTk5LTQ1ZWUtYTEzMC1mYjY2NzRmNjk5YTQiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjcwMDIiLCJhdWQiOiJUT0tFTiJ9.MTcBjskpqvzH_rcxrU3G1N-PiK7UvHgZ75cQfYiZsQJBBqgKROAlgxoVaD91oZF3TO00HHersxgZVDwTzXxuAg"
    }
  }
}

#Accepting Credential Offers

For a user's wallet to accept the credential via the credential offer URL, the URL must be parsed and the offer fulfilled. The Wallet API manages this process once provided the offer URL. More sophisticated scenarios include presenting the credentials to the user before accepting the credential offer. See an example below.

Accepting the offer

Accept the offer by making a POST call to the /wallet-api/wallet/{wallet}/exchange/useOfferRequest endpoint. This requires passing a user's did and the walletId in the parameters and the offer URL in the body. The API will parse the request, receive the credentials from the issuer, and store them in the user's wallet.

Example Call | Api Reference

curl -X 'POST' \
  'http://0.0.0.0:7001/wallet-api/wallet/{wallet}/exchange/useOfferRequest?did=did%3Akey%3Az6MknMppUdsg34t6oPevGDijgB9w9862Ai6Xu5iexjNU2Uoh' \
  -H 'accept: */*' \
  -H 'Content-Type: text/plain' \
  -d 'openid-credential-offer://issuer.portal.walt.id/?credential_offer=<credential_offer>'

You can receive the needed wallet id parameter via the /wallet-api/wallet/accounts/wallets endpoint.

#Display The Credential To The User

To improve readability, use the /wallet-api/util/parseMDoc endpoint to decode the CBOR-encoded mDL into a simple JSON structure.