Authorization Endpoint

⚠️ 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 uses this endpoint to ask the Holder’s Wallet for specific credentials, described via a Digital Credentials Query Language (DCQL) object.

---

Endpoint

Query Parameters

Name	Type	Required	Description
response_type	string	✅	Must be vp_token.
response_mode	string	✅	Must be one of: fragment or direct_post.jwt.
client_id	string	✅	Identifier of the Verifier. Must be one of: • A pre-registered client ID, or • A hash-bound identifier of the form x509_hash:<base64url(SHA-256(DER(cert)))>. When using x509_hash, the request must be signed using the corresponding X.509 certificate.
redirect_uri	string	✅	Callback endpoint for receiving the Verifiable Presentation response. Example: https://verifier.com/callback.
dcql_query	object	✅	A JSON object describing the requested credentials, URL-encoded as a string.
nonce	string	✅	Strong cryptographic random value to prevent replay attacks. Must be validated in the response.
state	string	❌	Verifier-generated value to maintain application state.
client_metadata	object	❌	Provides capabilities and cryptographic preferences of the Verifier’s client (e.g., supported algorithms and keys). Used by the Wallet to determine compatible formats and encryption methods for returning Verifiable Presentations

• When using client_id with x509_hash:, either the request parameter or request_uri must be provided, and the object must be signed by the private key corresponding to the X.509 certificate used to generate the hash.
• When using response_mode=direct_post.jwt, the redirect_uri is referred to as response_uri.
• Only pre-registered clients may omit the signature requirement.

---

Example Request (with pre-registered client)

GET /v1/oid4vp/authorize?
  response_type=vp_token&
  response_mode=fragment&
  client_id=1&
  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&
  client_metadata=%7B%22vp_formats_supported%22%3A%7B%22jwt_vc_json%22%3A%7B%22alg_values%22%3A%5B%22ES256%22%2C%22EdDSA%22%5D%7D%2C%22dc%2Bsd-jwt%22%3A%7B%22sd-jwt_alg_values%22%3A%5B%22ES256%22%2C%22EdDSA%22%5D%2C%22kb-jwt_alg_values%22%3A%5B%22ES256%22%2C%22EdDSA%22%5D%7D%2C%22mso_mdoc%22%3A%7B%22issuerauth_alg_values%22%3A%5B-7%2C-8%5D%2C%22deviceauth_alg_values%22%3A%5B-7%2C-8%5D%7D%7D%2C%22encrypted_response_enc_values_supported%22%3A%5B%22A256GCM%22%5D%2C%22jwks%22%3A%7B%22keys%22%3A%5B%7B%22alg%22%3A%22ECDH-ES%22%2C%22kty%22%3A%22EC%22%2C%22x%22%3A%22oW9RHgp_1FFS43FIbslV28ojaiSL8A8Cj-00hhhVw7Y%22%2C%22y%22%3A%227FcafbJDhOrsP2ubS_c9aPA4Qp_5vLG-l3L5EumTDSw%22%2C%22crv%22%3A%22P-256%22%7D%5D%7D%7D&
  nonce=1b9c3c4a-b1f5-4a27-ae6b-91d7b0c1a58f&
  state=your_state

---

Example Request (with x509_hash client)

GET /v1/oid4vp/authorize?
  client_id=x509_hash:ZFrfEjA07nTjUHzW_1EQY6AbCHyk7c04xZ7uSdBNzqw&
  request=eY......

---

Example dcql_query object

{
  "credentials": [
    {
      "id": "some_identity_credential",
      "format": "dc+sd-jwt",
      "meta": {
        "vct_values": ["https://credentials.example.com/identity_credential"]
      },
      "claims": [
        { "path": ["last_name"] },
        { "path": ["first_name"] }
      ]
    }
  ]
}

Example client_metadata object

{
  "vp_formats_supported": {
    "jwt_vc_json": {
      "alg_values": ["ES256", "ES256K", "RS256"]
    },
    "dc+sd-jwt": {
      "sd-jwt_alg_values": ["ES256", "ES256K", "RS256"],
      "kb-jwt_alg_values": ["ES256K"]
    },
  },
  "encrypted_response_enc_values_supported": ["A256GCM"],
  "jwks": {
    "keys": [
      {
        "alg": "ECDH-ES",
        "kty": "EC",
        "x": "oW9RHgp_1FFS43FIbslV28ojaiSL8A8Cj-00hhhVw7Y",
        "y": "7FcafbJDhOrsP2ubS_c9aPA4Qp_5vLG-l3L5EumTDSw",
        "crv": "P-256"
      }
    ]
  }
}

When sent in the URL, these objects must be JSON-encoded and then URL-encoded.

---

Response

Once the Wallet processes the request:

• If response_mode=fragment:
  The Wallet redirects the browser back to redirect_uri, with vp_token and other parameters in the URL fragment.

• If response_mode=direct_post.jwt:
  The Wallet sends a direct POST request to the redirect_uri, containing a signed JWT.

---

Authorization Request (request_uri)

Using a Request Object is RECOMMENDED to prevent large URL issues.

Example:

GET /v1/oid4vp/authorize?
  client_id=x509_hash:ZFrfEjA07nTjUHzW_1EQY6AbCHyk7c04xZ7uSdBNzqw&
  request_uri=https://verifier.com/authorization_request

The request_uri points to a public endpoint containing the signed Authorization Request Object. When present, the Wallet fetches this object directly.