Server-Side VP Queries

This page explains how the Verifier Service allows you to create, retrieve, and delete Verifiable Presentation (VP) query configurations. A VP query configuration defines what credentials and fields a verifier requests from a user. These configurations live on the server side so they can be reused across multiple authorization flows.


Overview

  • VP query configurations are managed by the Verifier Service itself, not only by client code.

  • Each configuration is stored as a JSON array of query parameters that specify which parts of a credential to request and any constraints on those values.

  • Once created, a configuration is assigned a unique identifier and can be fetched or removed by its ID.


Create VP Query Request

Type: CreateVpQueryRequestDto

Request Body

  • query (array of VPQueryParams, required) A non-empty array where each element defines a set of parameters for a Verifiable Presentation (VP) query. Each VPQueryParams element contains:

    • fields (array of InputDescriptorField, required) A list of descriptor fields specifying which parts of a credential to inspect and how to validate them. Each InputDescriptorField includes:

      • path (array of strings, required) One or more JSONPath expressions indicating where in the credential to extract a value.

      • filter (object, optional) A JSON Schema (Draft 7) that the extracted value(s) must conform to.


Controller Endpoints

All VP query–related endpoints are under the /api/v1/verifier/vp-queries path. Every endpoint requires a valid client‐secret bearer token for authentication.

  1. Create a VP Query Configuration

    • Method: POST

    • Path: /api/v1/verifier/vp-queries

    • Request Body: A JSON object with a query property, which is a non-empty array of VP query parameter sets.

    • Success Response (201 Created): Returns the newly created VP query configuration, including its ID, the full query array, and the creation timestamp.

    • Error Response (400 Bad Request): If the query array is missing, empty, or fails validation.

  2. Retrieve All VP Query Configurations

    • Method: GET

    • Path: /api/v1/verifier/vp-queries

    • Success Response (200 OK): Returns a JSON array of all stored VP query configurations (each with its ID, query body, and creation timestamp).

    • Error Response (400 Bad Request): If something goes wrong with the request format.

  3. Retrieve a VP Query Configuration by ID

    • Method: GET

    • Path: /api/v1/verifier/vp-queries/{id}

      • Replace {id} with the UUID of the configuration you want.

    • Success Response (200 OK): Returns the single VP query configuration matching that ID.

    • Error Response (400 Bad Request): If the provided ID is not a valid UUID.

    • Error Response (404 Not Found): If no configuration exists with the given ID.

  4. Delete a VP Query Configuration by ID

    • Method: DELETE

    • Path: /api/v1/verifier/vp-queries/{id}

      • Replace {id} with the UUID of the configuration you want to delete.

    • Success Response (204 No Content): The specified configuration was successfully removed from the database.

    • Error Response (400 Bad Request): If the provided ID is malformed.

    • Error Response (404 Not Found): If no configuration exists with that ID.


Because these VP queries live on the server side, you can standardize and manage them centrally rather than building the same query structure repeatedly in each client application.

Last updated