Skip to content
Documentation

Initiate the verification session with an external wallet.

POST
/verification-session/initiate

This API is intended to be called when attempting to initiate a verification session with an external wallet via OpenID for Verifiable Presentations protocol.

To do so, the caller should essentially:

  • Define what the wallet should present. This includes specifying the type of credential (e.g. org.iso.18013.5.1.mDL), its format (e.g. mso_mdoc), and claims that ought to be disclosed. More details can be found in the definition of a credentialDescription schema.
  • Configure their trust policy. This includes specifying the roots of trust that will be valid throughout the verification session (e.g. by pointing to a well-known trusted list or by explicitly providing trusted certificates). These are used to validate the authenticity of the Credential Issuer. More details can be found in the definition of a trustConfig schema.
  • Configure the protocol details. This includes defining OpenID4VP specifics such as clientIdScheme or responseMode. More details can be found in the definition of a protocolConfig schema.

Based on that information, Verification Service will create a new verification session, prepare the corresponding Authorization Request, and serve it.

In the response, the caller will obtain the following:

  • verificationSessionId — representing the unique identifier of the newly-created verification session.
  • authorization_request — URL encoded Authorization Request

Once the wallet obtains the authorization_request, the remainder of the verification protocol is done directly between Verification Service and the wallet through the appropriate Protocol APIs.

The caller can gain additional information about the verification session status through the /verification-session/status/{verificationSessionId} endpoint.

Note

The mso_mdoc credential format is not compatible with the direct_post response mode and will result in an error. This configuration is not supported by the mDL specifications.

Request Body required

object
credentialDescription
required

Description of a credential to be presented.

object
credentialType
required

Type of the credential to be presented, corresponds to vct in case of vc+sd-jwt, or docType in case of mso_mdoc.

string
org.iso.18013.5.1.mDL
credentialFormat
required

Format of the credential to be presented.

string
Allowed values: vc+sd-jwt mso_mdoc 
mso_mdoc
disclosurePaths

A list of paths to the attributes to be disclosed.

When credentialFormat is set to "mso_mdoc", the disclosurePaths entries must contain exactly two values, representing a (namespace, key) pair, and the value under that (namespace, key) pair will be disclosed in its entirety.

Array<Array>
[
  [
    "org.iso.18013.5.1",
    "given_name"
  ],
  [
    "org.iso.18013.5.1",
    "family_name"
  ],
  [
    "org.iso.18013.5.1",
    "resident_country"
  ]
]
trustConfig
required

Roots of trust used to validate the authenticity of Credential Issuer(s).

Details TBD

Array
[]
protocolConfig

Configuration instantiating a specific flavour of the OID4VP protocol for this verification session.

If omitted, the default values will be used, allowing the integration with wallets based on EUDI Reference implementation.

object
clientIdScheme

Parameter instructing the external wallet how to interpret the client_id in the context of client authentication. This will be included in the AuthorizationRequest.

string
default: redirect_uri
Allowed values: redirect_uri pre-registered
responseMode

Parameter describing a mechanism by which the wallet should send the Authorization Response.

string
default: direct_post.jwt
Allowed values: direct_post direct_post.jwt

Responses

200

Session initiated successfully.

object
verificationSessionId
required

The unique ID of the verification session.

string format: uuid
authorization_request
required

The URL encoded AuthorizationRequest object intended to be communicated to an external wallet.

The object contains the following information:

  • client_id — The identifier of an “OAuth2” client (“Verifier” in this case) in the “Oauth2” Authorization Flow. The client_id is prefixed with client_id_scheme that is used when external wallet needs to interpret client_id in the context of client authentication. The default value is "redirect_uri" that is described more in depth here. More details about client_id syntax can be found here.
  • response_uri — Defining the URI where the external wallet must send the Authorization Response using an HTTP POST request as defined by the Response Mode "direct_post".
  • response_type — Always set to "vp_token" as described in the standard.
  • response_mode — Defining the mechanism by which the wallet should send the Authorization Response. This parameter will always be assigned the value provided in the request. If the value is omitted in the request, the "direct_post.jwt" parameter will be set with the semantics described here.
  • presentation_definition_uri — Defining the URI where the wallet should retrieve the presentation_definition from.
  • nonce — A string of ASCII URL safe characters as defined by OpenID.Core used to securely bind the Verifiable Presentation(s) provided by the Wallet to the particular transaction.
  • state — Parameter used to link the appropriate Authorization Requests and Authorization Responses. More details are available in the state-management section of the OID4VP.
  • client_metadata — Determines credential formats, proof types and algorithms supported by the Verifier.
string
openid4vp://authorize?client_id=https%3A%2F%2Fverification-service%2Fprotocol&response_uri=https%3A%2F%2Fverification-service%2Fprotocol%2Fauthorization-response&response_type=vp_token&response_mode=direct_post.jwt&presentation_definition_uri=https%3A%2F%2Fverification-service%2Fprotocol%2Fpresentation-definition%2F550e8400-e29b-41d4-a716-446655440000&nonce=n-0S6_WzA2Mj&state=da013b3b-f7ec-4ccd-8d41-c34cde9598a3&client_metadata=%7B%22vp_formats%22%3A%7B%22vc%2Bsd-jwt%22%3A%7B%22sd-jwt_alg_values%22%3A%5B%22ES256%22%5D%2C%22kb-jwt_alg_values%22%3A%5B%22ES256%22%5D%7D%7D%7D

400

Bad request (e.g. missing required field, invalid data, invalid JSON Schema).

object
message

Error message

string
Missing required field - credentialDescription.credentialFormat

500

Internal Server Error

object
message

Error message

string
Internal Server Error