Mobile Driver's License Verification API

This API facilitates interactions with a digital wallet for mDL verifiable credentials, following Annex A of the ISO/IEC TS 18013-7:2024 standard (REST API). The purpose of this API is to simplify credential exchange as much as possible. It achieves this by abstracting and managing the trust relationship with credential issuers and implementing the complex protocol that verifies and communicates with a compliant wallet.

The primary function is to initiate and manage verifications and report their status to the requesting party. This allows the complex interactions between reader and wallet to be abstracted from the act of verifying a document. The reader (website) initiates a verification, and the Mobile Driver's License Verification API responds with a Verification ID and an engagement URI for communication with the wallet.  The reader can then begin polling the API for receiving claims. This API exclusively uses application/json for request and response bodies.

Create verification request

This endpoint initiates a new verification process.  It accepts a POST request specifying the desired protocol for interacting with the wallet and a template ID referencing a pre-configured verification template.

The response includes a verification ID along with an engagement URI for engaging the wallet based on the specified protocol.

Endpoint

POST /vdcs/verification

Scopes

create:verification_request

Body parameters

  • protocol: String. Required

    Engagement protocols define the methods your application uses for interacting with the wallet. We currently support:

  • template_id: String. Required

    The ID references a pre-configured template. This simplifies the request by using pre-defined claim requirements.

Response schema

Response Code Response Type Description
201 application/json
  • verification_idString

    Verification ID (UUIDv4) as received from the verification initiation. This ID is used for subsequent interactions with the verification API, such as polling for status.

  • engagementString

    MDoc URI for the Web API protocol. This URI should be presented to the user to initiate the wallet interaction using the protocols. It conforms to the structure defined in ISO/IEC DTS 18013-7 (Annex 4)

Response codes

Response Code Response Message Description
201 Verification is initiated successfully The response body contains the Response Schema defined above.
400 Bad Request The request is malformed or invalid.
401 Unauthorized The request requires authentication. Ensure a valid access token is provided in the Authorization header.
403 Forbidden Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.
404 Template not found The provided template ID is invalid or no longer active.
500 Internal Server Error An unexpected error occurred on the server.

Get verification status

This endpoint retrieves the status and, if available, the claims of a given verification.  The id path parameter specifies the Verification ID.

Endpoint

GET /vdcs/verification/{id}

Scopes

read:verification_request

Path parameters

verification_id: String. Required

  • Verification ID (UUIDv4) as received from the verification initiation. This ID is used for subsequent interactions with the Mobile Driver's License Verification API, such as polling for status.

Response schemas

Response Code Response Type Description
200 application/json state: String Required

The state field contains information about the current state of the verification process. The following values may be present:

  • pending-engagement: The verification service is waiting initial engagement from the wallet.
  • pending-mdoc: The verification service is waiting presentation of the mDoc from the wallet.
  • error-wallet: An error occurred when interacting with the wallet. The reason field will contain more information regarding the encountered error.
  • error-reader: An error has occurred when reading the mDoc. The reason field will contain more information regarding the error encountered.
  • honored: Verification completed without issue. The verified document is available in the presentation field for consumption.

reason: String Optional

The reason field contains additional information (if available) regarding the state of the verification request.

presentation: Object Optional

The presentation field contains the claims provided by the wallet in response to the presentation definition. It follows a simplified structure based on namespaces and claims. Each claim includes a value, retain flag, and verified status.

Response codes

Response Code Response Message Description
401 Unauthorized The request requires authentication. Ensure a valid access token is provided in the Authorization header.
403 Unauthorized Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.
404 Verification not found The provided verification ID is invalid or no longer active.
500 Internal Server Error Verification failed. Response body may contain an ErrorResponse object with details about the failure. Check the reason field for specific error information.