Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

OpenID4VP authorization request parameters

OpenID for Verifiable Presentations (OpenID4VP) is an OpenID specification that lets a relying party ask a wallet for a verifiable presentation. A verifiable presentation is a credential that the wallet presents for its holder, together with cryptographic proof that the holder approved the presentation.

The relying party encodes an OpenID4VP authorization request as a set of URL parameters. The wallet reads the parameters, asks the user for consent, and returns an authorization response. This page lists the request parameters, the client identifier schemes, the response modes, and the application link scheme. The EU Age Verification Profile fixes the value of several of these parameters.

A relying party can also send the same request to the W3C Digital Credentials API instead of a URL. For the comparison between the two protocols, see Protocol modes.

Authorization request parameters

ParameterRequiredDescriptionValue in the age verification profile
response_typeYesRequests a verifiable presentation token.vp_token
client_idYesIdentifies the relying party. The value carries a scheme prefix. See Client identifier schemes.redirect_uri: followed by the response URI
nonceYesA random value that binds the presentation to this one transaction.A fresh random string for every request
response_modeYesSelects how the wallet returns the authorization response. See Response modes.direct_post
response_uriConditionalThe endpoint that receives the wallet POST. Required when response_mode is direct_post.An HTTPS URL on the relying party
dcql_queryConditionalThe query for the credentials and claims. See DCQL queries.A DCQL JSON object
stateNoAn opaque value that correlates the response with the request.A random string, or omitted
presentation_definitionConditionalA DIF Presentation Exchange query. OpenID4VP accepts this field or dcql_query, but not both.Not used
client_metadataNoMetadata about the relying party, such as a display name and the supported presentation formats.Omitted
scopeNoOpenID Connect scopes.Not used
redirect_uriNoA fallback redirect after the response is delivered.Not used with direct_post

Either presentation_definition or dcql_query must be present, but not both. The EU Age Verification Profile requires dcql_query.

Note

The nonce and state values are 22-character base64url strings in this system. They carry 128 bits of entropy, which is equivalent to a UUID version 4, and the specification does not require the UUID format.

Client identifier schemes

The client_id parameter starts with a scheme prefix. The prefix tells the wallet how to interpret the identifier and how much trust to place in it. Different profiles require different schemes.

SchemeIdentifier formatSigned requestTrust mechanismProfile
redirect_uri:The prefix plus the response URI, for example redirect_uri:https://rp.example.com/callback.NoTLS and the web PKIEU Age Verification Profile (Annex A)
x509_san_dns:The prefix plus a DNS name, for example x509_san_dns:rp.example.com.Yes, a JAR signed with an x5c headerThe DNS subject alternative name of a certificateHAIP (EUDI Wallet)
x509_hash:The prefix plus a certificate hash.Yes, a JAR signed with an x5c headerThe hash of an X.509 certificateHAIP (EUDI Wallet)
verifier_attestation:The prefix plus an attested identifier, for example verifier_attestation:my-verifier.Yes, a JAR signed with a jwt headerA JWT from a trusted attestation issuerHAIP (optional)
No prefix (pre-registered)The identifier alone.OptionalPre-configured in the walletCustom deployment

The redirect_uri scheme

The client_id value equals the response_uri, as in client_id=redirect_uri:https://rp.example.com/ewqwe_api/openid4vp/direct_post. The request is unsigned. It carries no JWT-secured authorization request (JAR), no x5c header, and no cryptographic verification. Trust rests on TLS and the web PKI. This scheme is the simplest to implement and is the one that the EU Age Verification Profile mandates.

The x509_san_dns scheme

The client_id value is a DNS name that matches a subject alternative name (SAN) in an X.509 certificate, as in client_id=x509_san_dns:rp.example.com. The request must be signed as a JAR (RFC 9101), and the x5c JOSE header carries the certificate chain. The wallet validates the certificate against its reader trust store, so the root certificate authority of the relying party must be trusted by the wallet.

Other schemes

The x509_hash scheme identifies the relying party by the hash of its certificate instead of by a DNS name. The verifier_attestation scheme identifies the relying party by an identifier that a trusted attestation issuer attests. The verifier_attestation scheme needs a published trust framework with designated attestation issuers, and no such framework exists for general age verification. The pre-registered scheme uses a plain identifier that the wallet holds in its configuration.

Response modes

The response_mode parameter selects how the wallet returns the authorization response.

ModeDescriptionUse
fragmentThe wallet returns the VP token in the URL fragment.Same-device flows. Not used by the age verification profile.
direct_postThe wallet posts the VP token to the response_uri.Cross-device flows. Required by the age verification profile.
direct_post.jwtThe wallet posts an encrypted JWT to the response_uri.Optional privacy extension. Used by HAIP.

The relying party builds the request URL with the av:// scheme for a same-device flow. The operating system opens the age verification application that registered the scheme. The wallet then returns the response through direct_post, which is a separate HTTP POST to the response_uri.

Complete example authorization request

The following URL is a complete authorization request for a same-device flow. All parameters appear by value in the URL.

av://?response_type=vp_token&response_mode=direct_post&client_id=redirect_uri%3Ahttps%3A%2F%2Frp.example.com%2Fewqwe_api%2Fopenid4vp%2Fdirect_post&response_uri=https%3A%2F%2Frp.example.com%2Fewqwe_api%2Fopenid4vp%2Fdirect_post&nonce=tMQ3X8j5LwnKpZiHvRqCaA&state=A7kB2mN9xYzL4pWqRsGtUj&dcql_query=%7B%22credentials%22%3A%5B%7B%22id%22%3A%22eu_av_proof%22%2C%22format%22%3A%22mso_mdoc%22%2C%22meta%22%3A%7B%22doctype_value%22%3A%22eu.europa.ec.av.1%22%7D%2C%22claims%22%3A%5B%7B%22path%22%3A%5B%22eu.europa.ec.av.1%22%2C%22age_over_18%22%5D%7D%5D%7D%5D%7D

The same request, with the parameters decoded:

ParameterDecoded value
response_typevp_token
response_modedirect_post
client_idredirect_uri:https://rp.example.com/ewqwe_api/openid4vp/direct_post
response_urihttps://rp.example.com/ewqwe_api/openid4vp/direct_post
noncetMQ3X8j5LwnKpZiHvRqCaA
stateA7kB2mN9xYzL4pWqRsGtUj
dcql_queryThe JSON object shown below

The decoded dcql_query value:

{
  "credentials": [
    {
      "id": "eu_av_proof",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"]
        }
      ]
    }
  ]
}

Authorization response parameters

The wallet sends the authorization response to the response_uri as an application/x-www-form-urlencoded body.

ParameterRequiredDescription
vp_tokenYesCarries the verifiable presentation. With a DCQL query, the token is a JSON object whose keys are credential identifiers and whose values are arrays of presentations.
presentation_submissionNoMaps the presentation to the request. The wallet does not send this field with a DCQL query.
stateNoAn echo of the state value from the request.