#Accept mDL/mDOC Credentials via OID4VCI

In this guide, we take a look at how you can use the walt.id Enterprise wallet service API to accept an mDL (mobile Driving License) or mDOC credential from an issuer via OID4VCI.

Ensure you have set up a wallet (service) and linked the necessary enterprise services (e.g., Credential Store) before proceeding with this guide.

Our implementation for mDL/mDOC credentials currently only supports binding to secp256r1 keys.

#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://.

Example Offer URL

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

Example of a Credential Offer Object for mDL/mDOC

{
  "credential_issuer": "https://issuer.demo.walt.id",
  "credential_configuration_ids": [
    "org.iso.18013.5.1.mDL"
  ],
  "grants": {
    "authorization_code": {
      "issuer_state": "<issuer_state>"
    },
    "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
      "pre-authorized_code": "<pre-authorized_code>",
      "user_pin_required": false
    }
  }
}

#Accepting mDL/mDOC Credential Offers

mDL/mDOC credentials follow the ISO 18013-5 standard and provide structured data for identity documents like driving licenses.

CURL

Endpoint: /v1/{target}/wallet-service-api/credentials/receive | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/wallet-service-api/credentials/receive' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "offerUrl": "openid-credential-offer://issuer.example.org/issue/?credential_offer_uri=https%3A%2F%2Fissuer.example.org%2FcredentialOffer%3Fabc123xyz789",
  "keyReference": "example.kms.key1",
}'

Path Parameters

orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
target: resourceIdentifier - The target indicates the organization + tenant + wallet which should be used to receive the credential ({organizationID}.{tenantID}.[walletID]), e.g. waltid.tenant1.wallet1

Body Parameters

offerUrl String - An OID4VCI offer URL.
keyReference (optional) String - The resource ID (target) of the key to which the received credential should be bound. Beware that the key must be a Secp256r1 key.
key (optional) Object - A key object or reference key object for external KMS. Beware that the key must be a Secp256r1 key.
metadata (optional) Object - Arbitrary JSON object that will be stored together with the credential.
runPolicies (optional) Boolean - If set to true, the wallet service will run any holder policies.

Response Codes

201 - mDL/mDOC Credential received successfully.

Body

{
    "offeredCredential": {
      "format": "mso_mdoc",
        "doctype": "org.iso.18013.5.1.mDL",
        "credential_definition": {
          "type": [
            "org.iso.18013.5.1.mDL"
          ]
        },
        "cryptographic_binding_methods_supported": [
          "cose_key"
        ]
      },
    "credentialResponse": {
      "format": "mdoc",
      "credential": "a267646f6354797065756f72672e69736f2e31383031332e352e312e6d444c6c6973737565725369676e6564a26a6e616d65537061636573a1716f72672e69736f2e31383031332e352e318bd8185852a4686469676573744944006672616e646f6d504c695c9b82008c5431330feae284019d71656c656d656.....",
    }
}

Last updated on November 4, 2025

Accept SD-JWT Verifiable Credentials via OID4VCI Credential Acceptance