Skip to main content
⚠️ This API is under active development, please contact us for help ⚠️
The Authorization Endpoint initiates a Verifiable Presentation request using OpenID for Verifiable Presentations (OpenID4VP). The Verifier sends this request to the Holder’s Wallet to request specific credentials based on a Digital Credentials Query Language (DCQL).

​
Endpoint

​
Query Parameters

NameTypeRequiredDescription
response_typestring✅Must be vp_token.
response_modestring✅Must be one of: fragment or direct_post.jwt.
client_idstring✅Identifier of the Verifier (your server). Must match the x509_san_dns in your TLS certificate. Example: verifier.com. If the value is prefixed with x509_san_dns:, domain ownership will be verified. Without the prefix, it is treated as a pre-registered client.
redirect_uristring✅Verifier’s callback endpoint to receive the presentation response. Example: https://verifier.com/callback.
dcql_queryobject✅A JSON object describing the requested credentials, URL-encoded as a string.
noncestring✅Strong cryptographic random value to prevent replay attacks. Must be validated in the response.
statestring❌Verifier-generated value to maintain application state.
  • Only pre-registered client is supported at this moment. Please contact us to get your site whitelisted.
  • When using response_mode=direct_post.jwt, the redirect_uri is referred to as response_uri.

​
Example Request

GET /v1/oid4vp/authorize?
  response_type=vp_token&
  response_mode=fragment&
  client_id=x509_san_dns:verifier.com&
  redirect_uri=https%3A%2F%2Fverifier.com%2Fcallback&
  dcql_query=%7B%22credentials%22%3A%5B%7B%22id%22%3A%22some_identity_credential%22%2C%22format%22%3A%22dc%2Bsd-jwt%22%2C%22meta%22%3A%7B%22type_values%22%3A%5B%5B%22KycCredential%22%5D%5D%2C%22vct_values%22%3A%5B%22https%3A%2F%2Fcredentials.example.com%2Fidentity_credential%22%5D%7D%2C%22claims%22%3A%5B%7B%22path%22%3A%5B%22last_name%22%5D%7D%2C%7B%22path%22%3A%5B%22first_name%22%5D%7D%5D%7D%5D%7D&
  nonce=1b9c3c4a-b1f5-4a27-ae6b-91d7b0c1a58f&
  state=your_state

​
Example dcql_query object

JSON
{
  "credentials": [
    {
      "id": "some_identity_credential",
      "format": "dc+sd-jwt",
      "meta": {
        "type_values": [["KycCredential"]],
        "vct_values": ["https://credentials.example.com/identity_credential"]
      },
      "claims": [
        {
          "path": ["last_name"]
        },
        {
          "path": ["first_name"]
        }
      ]
    }
  ]
}
When sending in the URL, the object must be JSON-encoded and URL-encoded.

​
Response

Once the wallet processes the request:
  • If response_mode=fragment: The wallet will redirect the browser back to redirect_uri with the vp_token and other parameters in the fragment part of the URL.
  • If response_mode=direct_post.jwt: The wallet will send a direct POST request to the redirect_uri containing a signed JWT.

​
Authorization Request (request_uri)

Use of Authorization Requests is RECOMMENDED to avoid issues caused by large request sizes. Example of Authorization Request Using request_uri: 
GET /v1/oidc4vp/authorize?
  client_id=x509_san_dns:verifier.com&
  request_uri=https://verifier.com/authorization_request
The request_uri points to a public endpoint with the Authorization Request Object. When present, the Wallet fetches this object directly.