mdoc/mDL

Proven and the Holdr SDK provide the capability to issue, hold, and verify credentials in the mdoc/mDL format over a variety of protocols. The following documentation describes how to use Proven for the server portions of mdoc/mDL workflows.

There are currently four categories of APIs for working with mdoc/mDL credentials over OID4VC: Keys, Schemas, Issuance, and Verification. These categories of APIs should be approached sequentially, e.g. it doesn't work to use the verification APIs if you haven't configured keys.

Keys

Key Initialization

Provision mDoc issuer key material so that you can securely issue mdoc and mDL credentials.

Example curl Command:

curl --location 'https://buckets4life.share.zrok.io/api/v1/oid4vci/setup/mdoc' \
--header 'x-api-key: HuNsaIP9w0LsM5vqRhWprqLShgWLvb2yMAyuYUjWqd4=' \
--header 'Content-Type: application/json' \
--header 'Cookie: sessionId=s%3AIxantPaS5ZGMmrHZDetRQHQIVTRBiNBL.DAjBpQO8pxrjJdM4jQUYJU%2FlxzGAGIJcUzM%2FM7zltk0' \
--data '{
  "force": false 
}'

Request (POST)

• force {boolean}: Whether to force the creation of a new key or not. Use false for first-time initialization or in case you don't want to overwrite the key (if one exists). Use true to rotate the key.

Response

• key_id {string}: This string will allow you to identify the key that the system is using for mdoc, allowing you assess the state of the system (e.g., are we still using the same key as 6 months ago?). Useful to save. Sample: 8d3e8f18-5e7d-4f1a-a72b-1db2f1d0c001

• cert_id {string}: This string will allow you to identify the certificate that the system is using to identify itself to other entities, allowing you to assess the state of the system (e.g. is this the endpoint or agent I think it is?). Useful to save. Sample: 6af84a3c-b6e9-4b1c-844a-6ce6a1f2d002

• message {string}: Human readable text that describes the result of the operation (e.g., mDoc issuer keys provisioned successfully). Sample: mDoc issuer keys provisioned successfully.

Use this API to check whether the agent has been initialized with mdoc issuer key material and is ready to issue credentials.

No request body or parameters.

• keys {array of objects}: The key(s) currently provisioned for mdoc issuance. Each object contains:

  • key_id {string}: The identifier of the provisioned key. Sample: 8d3e8f18-5e7d-4f1a-a72b-1db2f1d0c001

  • cert_id

Use this API to configure the system to issue credentials of a particular schema, i.e. set things up so you can issue mDLs, passports, national IDs, etc.

• doctype {string} Required: The mdoc document type identifier (e.g., org.iso.18013.5.1.mDL).

• label {string}: A human-readable name for this credential type (e.g., Mobile Driver's License).

• description

• agentRecord {object}: The record created in the agent.

  • supported_cred_id {string}: Unique identifier for this credential type in the agent. Sample: 9fd5ef9d-b8b8-4f52-b6a9-95b9ce4f6f8a

  • identifier

Optional query parameters:

• doctype {string}: Filter results to a specific document type.

• config_id {string}: Filter results to a specific configuration record.

Returns an array of configuration objects, each with the same fields as the dbConfig object in the POST response above.

Use this API to create a credential exchange and generate an offer that can be delivered to a holder's wallet.

• supported_cred_id {string}: The ID of the registered credential type to issue, obtained from the Schema Setup step. Sample: 9fd5ef9d-b8b8-4f52-b6a9-95b9ce4f6f8a

• credential_subject {object}: The claims to include in the credential. Keys should match the claims defined when the credential type was registered. For an mDL, common fields include family_name, given_name, birth_date, issue_date

• offer {object}: The credential offer object, suitable for delivery to a holder's wallet.

  • credential_issuer {string}: The URL of the credential issuer. Sample: https://example/oid4vc/tenant/c286d1c7-c548-48d1-8580-76d3fe317bff

  • credentials

Verification is a multi-step process. First, you create a presentation definition that describes what claims you want to verify. Then, you use that definition to create a presentation request, which generates a URI that can be delivered to a holder's wallet (e.g., as a QR code). Finally, after the holder responds, you retrieve the presentation results.

Use this API to define what credentials and claims you want to request from a holder.

pres_def {object}: The presentation definition object, following the DIF Presentation Exchange specification.

• id {string}: An optional identifier for the presentation definition. If omitted, the system will generate one.

• purpose {string}: A human-readable string describing the purpose of the verification request.

• input_descriptors {array of objects}: One or more descriptors specifying what credentials and claims are required.

• pres_def_id {string}: The system-generated identifier for this presentation definition. Save this — you will need it to create a presentation request. Sample: 42c870ae-b605-4121-b5e3-1e6bb3a00c6f

• pres_def {object}: The presentation definition as stored, including any system-generated fields such as id.

Retrieve all presentation definitions registered for your wallet.

No request body or parameters.

Returns an array of presentation definition objects, each with the same fields as the POST response for creating a presentation definition above.

• pres_def_id {string} (path parameter, required): The identifier of the presentation definition to retrieve.

Returns a single presentation definition object with the same fields as the POST response for creating a presentation definition above.

• pres_def_id {string} (path parameter, required): The identifier of the presentation definition to delete.

• Only an HTTP status response code is returned.

Use this API to generate a presentation request from a previously created presentation definition. The response includes a URI that can be rendered as a QR code or delivered as a deep link for the holder's wallet to scan.

• pres_def_id {string}: The identifier of the presentation definition to use, obtained from Step 1. Sample: 42c870ae-b605-4121-b5e3-1e6bb3a00c6f

• vp_formats {object}: The verifiable presentation formats to accept. For mdoc verification, use "mso_mdoc": { "alg": ["ES256"] }.

• request_uri {string}: A URL-encoded openid4vp:// URI. This is typically rendered as a QR code or deep link for the holder's wallet to scan or tap. Sample: openid4vp://?client_id=did%3Ajwk%3A...&request_uri=https%3A//example/oid4vc/tenant/.../oid4vp/request/43050ce4-bfb4-4454-b5de-9bbd1c564a85

• request {object}: The presentation request record.

After the holder's wallet responds to the presentation request, use this API to retrieve all of the results.

Optional query parameters:

• sort-field {string}: The field to sort by (default updated_at).

• sort-direction {string}: Sort direction, ASC or DESC (default DESC).

• params {object}: The pagination and filter parameters applied to the query.

• rows {array of objects}: The presentation records. Key fields on each record include:

  • presentation_exchange_id {string}: Unique identifier for the presentation exchange.

After the holder's wallet responds to the presentation request, use this API to retrieve a specific result.

• presentation_exchange_id {string} (path parameter, required): The identifier of the presentation exchange to retrieve.

Returns a single presentation record with the same fields as described in the list response above.