URL Schemes

Verification requests use different URL schemes depending on the protocol version, profile, and use case. This page explains when to use each one and how they differ.

URL schemes

openid4vp://

The standard OID4VP v1.0 scheme using DCQL queries.

openid4vp://?request_uri=https://api.verifiables.com/verifier/authorization/request.jwt/550e8400-e29b-41d4-a716-446655440000

Requests use this scheme when you set haip: false (or scheme: "openid4vp") with version: "v1". By default, v1 requests use the HAIP profile and the haip-vp:// scheme. France Identite wallets also accept openid4vp:// with HAIP payload conventions.

mdoc-openid4vp://

The legacy scheme from OID4VP Draft 18, using Presentation Exchange (PEX) queries.

mdoc-openid4vp://?request_uri=https://api.verifiables.com/verifier/authorization/request.jwt/550e8400-e29b-41d4-a716-446655440000

Use mdoc-openid4vp:// when you need compatibility with wallets that only support Draft 18, such as some early EUDI wallet implementations. Set version: "draft18" in the request body to use this scheme.

haip-vp://

The HAIP (High Assurance Interoperability Profile) scheme. Follows the OpenID4VP HAIP profile with stricter requirements.

haip-vp://?request_uri=https://api.verifiables.com/verifier/authorization/request.jwt/550e8400-e29b-41d4-a716-446655440000

HAIP mandates X.509 certificate-based client identification and specific algorithm choices. This is the default for version: "v1" requests (haip defaults to true).

eu-eaap://

The wallet invocation scheme ETSI TS 119 472-2 gives EUDI wallets. The request itself is whatever the other parameters produce (HAIP by default); only the scheme changes. The API never picks it on its own: pass scheme: "eu-eaap".

eu-eaap://?client_id=x509_hash%3A...&request_uri=https://api.verifiables.com/verifier/authorization/request.jwt/550e8400-e29b-41d4-a716-446655440000

Wallets outside the EUDI ecosystem may not register this scheme, so keep haip-vp:// or openid4vp:// for general use.

av://

The Age Verification profile scheme. All parameters are inline in the URL.

av://?response_type=vp_token&client_id=redirect_uri%3Ahttps%3A%2F%2Fapi.verifiables.com%2Fverifier%2Fauthorization%2Fresponse%2F<id>&redirect_uri=https%3A%2F%2Fapi.verifiables.com%2Fverifier%2Fauthorization%2Fresponse%2F<id>&response_mode=direct_post&dcql_query=...

The simplest scheme. No request_uri indirection, no encrypted responses. Only used when you explicitly pass scheme: "av" in the request body. See Age Verification for details.

When to use which

If you are unsure, start with the defaults (version: "v1", HAIP). They have the widest support and the most flexible query language.

Client ID schemes

The client_id_scheme determines how the wallet identifies and authenticates the verifier. Different schemes provide different trust levels.

redirect_uri

The client_id is the redirect URI itself. No verifier authentication.

{
  "client_id_scheme": "redirect_uri",
  "client_id": "redirect_uri:https://api.verifiables.com/verifier/authorization/response/<id>",
  "redirect_uri": "https://api.verifiables.com/verifier/authorization/response/<id>"
}

x509_san_dns

The client_id is a DNS name that appears in the Subject Alternative Name of the verifier's X.509 certificate. The wallet verifies the certificate chain.

{
  "client_id": "x509_san_dns:api.verifiables.com"
}

x509_hash

The client_id is derived from the hash of the verifier's X.509 certificate. Used by the HAIP profile.

{
  "client_id": "x509_hash:Uvo3HtuIxuhwKLj1S0YAKGFf6TnKuvcS7dn8X4qoTs0"
}

Scheme selection in the API

You can set the scheme explicitly with the scheme request parameter (openid4vp, mdoc-openid4vp, haip-vp, eu-eaap, or av). If you omit it, the API selects a scheme from the other request parameters:

The scheme is reflected in the url field of the response.