# OpenID for Verifiable Presentation APIs ## OID4VP Verifier API ### Create Verifier **`POST`** `/v1/orgs/{orgId}/oid4vp/verifier` Creates a new verifier within the specified organization. A verifier is an entity that requests and validates Verifiable Presentations (VPs) from credential holders using the OID4VP protocol. #### Path Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------------------ | | `orgId` | string | The unique identifier of the organization. | #### Request Body **Content-Type:** `application/json` | Field | Type | Required | Description | | ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `verifierId` | string | Yes | A unique name or identifier for the verifier within the organization. Used to reference the verifier in subsequent API calls (e.g. `"verifier-12345"`). | | `clientMetadata` | object | No | Display and branding information about the verifier application, presented to the holder when a presentation request is received. See [Client Metadata Object](#client-metadata-object) below. | #### Client Metadata Object | Field | Type | Required | Description | | ------------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------- | | `client_name` | string | No | Human-readable name of the verifier application shown to the holder (e.g. `"Example Verifier App"`). | | `logo_uri` | string (URL) | No | URL of the verifier's logo image displayed to the holder during a presentation request. | #### Sample Request Payload ```json { "verifierId": "verifier-12345", "clientMetadata": { "client_name": "Example Verifier App", "logo_uri": "https://example.com/logo.png" } } ``` #### Notes * `verifierId` must be unique per organization. Attempting to create a verifier with a duplicate ID will return a conflict error. * `clientMetadata` is optional but recommended — it provides the holder's wallet with context about who is requesting the presentation, improving trust and user experience. *** ## OID4VP Verification Template API ### Create Verification Template **`POST`** `/v1/orgs/{orgId}/oid4vp/verification-template` Creates a new verification template for the specified organization. A verification template defines the credential query rules (using the DCQL standard) and signing configuration for a Verifiable Presentation (VP) request. Once created, the template can be assigned by an ecosystem lead to specific intents as needed. #### Path Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------------------ | | `orgId` | string | The unique identifier of the organization. | #### Request Body **Content-Type:** `application/json` | Field | Type | Required | Description | | -------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Human-readable name for the verification template (e.g. `"Verification Template"`). | | `templateJson` | object | Yes | Contains the DCQL query definition that specifies which credentials and claims are required from the holder. See [Template JSON Object](#template-json-object) below. | | `signerOption` | string | Yes | Specifies the signing method used to sign the VP request sent to the holder's wallet. See [Signer Options](#signer-options) below. | #### Signer Options | Value | Description | | -------------- | ---------------------------------------------------------------------- | | `DID` | Signs the VP request using a Decentralized Identifier (DID). | | `X509_P256` | Signs the VP request using an X.509 certificate with P-256 key type. | | `X509_ED25519` | Signs the VP request using an X.509 certificate with Ed25519 key type. | #### Template JSON Object | Field | Type | Required | Description | | ------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- | | `dcql` | object | Yes | Wrapper for the DCQL (Digital Credentials Query Language) query definition. See [DCQL Query](#dcql-query) below. | #### DCQL Query The `dcql.query` object defines which credentials are required from the holder and how they are evaluated. | Field | Type | Required | Description | | ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `combine` | string | Yes | Logical operator for evaluating the credential set. `"all"` requires all specified credential sets to be satisfied. | | `credentials` | array | Yes | Array of individual credential query definitions. See [Credential Query Object](#credential-query-object) below. | | `credential_sets` | array | No | Groups credential queries into sets with flexible options. Allows the verifier to accept alternative credentials. See [Credential Set Object](#credential-set-object) below. | #### Credential Query Object Each entry in the `credentials` array defines a query for a specific credential the verifier wants to receive. | Field | Type | Required | Description | | -------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Yes | A unique identifier for this credential query within the template. Referenced in `credential_sets` to build flexible requirement groups. | | `format` | string | Yes | The expected credential format. Supported values: `dc+sd-jwt`, `mso_mdoc`. | | `meta` | object | No | Format-specific metadata to match the credential type. See [Meta Object](#meta-object) below. | | `claims` | array | No | Array of specific claims the verifier is requesting from the credential. See [Claim Object](#claim-object) below. | | `require_cryptographic_holder_binding` | boolean | No | If `true`, the wallet must prove cryptographic control of the credential (i.e. the holder must sign the presentation). Recommended to set `true`. | **Meta Object** The `meta` object provides credential-type matching criteria and differs by format. | Format | Field | Type | Description | | ----------- | --------------- | --------------- | ------------------------------------------------------------------------------------------ | | `mso_mdoc` | `doctype_value` | string | The mdoc document type to match (e.g. `"org.iso.23220.photoid.1"`). | | `dc+sd-jwt` | `vct_values` | array of string | Array of acceptable Verifiable Credential Type values (e.g. `["BirthCertificate-sdjwt"]`). | **Claim Object** Each entry in the `claims` array specifies a single claim the verifier wants disclosed from the credential. | Field | Type | Required | Description | | ------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `path` | array | Yes | JSON path to the claim within the credential. For `mso_mdoc`, the first element is the namespace and the second is the attribute key (e.g. `["org.iso.23220.1", "portrait"]`). For `dc+sd-jwt`, the path is the attribute key (e.g. `["first_name"]`). | | `intent_to_retain` | boolean | No | If `true`, the verifier intends to store the disclosed claim value after verification. Should be declared transparently to inform the holder. | #### Credential Set Object `credential_sets` allows the verifier to define flexible requirements — for example, accepting either credential A or credential B to satisfy the same requirement. | Field | Type | Required | Description | | ---------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `options` | array | Yes | Array of options, where each option is an array of credential query `id` values. The holder must satisfy at least one option. Each option is a combination of credential IDs that together fulfil the requirement. | | `required` | boolean | Yes | If `true`, the holder must satisfy at least one of the listed options. If `false`, the set is optional. | #### Sample Request Payload ```json { "name": "Verification Template", "templateJson": { "dcql": { "query": { "combine": "all", "credentials": [ { "id": "orgiso23220photoID1", "meta": { "doctype_value": "org.iso.23220.photoid.1" }, "claims": [ { "path": ["org.iso.23220.1", "portrait"], "intent_to_retain": true } ], "format": "mso_mdoc", "require_cryptographic_holder_binding": true }, { "id": "BirthCertificate-dc_sd_jwt", "meta": { "vct_values": ["BirthCertificate-sdjwt"] }, "claims": [ { "path": ["first_name"], "intent_to_retain": true } ], "format": "dc+sd-jwt", "require_cryptographic_holder_binding": true } ], "credential_sets": [ { "options": [ ["BirthCertificate-dc_sd_jwt"], ["orgiso23220photoID1"] ], "required": true } ] } } }, "signerOption": "DID" } ``` #### Notes * Once created, this template is available to the ecosystem lead to assign to specific verification intents. *** ## OID4VP Presentation Request APIs Two APIs are available for creating a Verifiable Presentation (VP) request. Both return a verification request that is sent to the holder's wallet. | API | Use Case | | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | [Intent-Based Verification Presentation](#intent-based-verification-presentation) | Uses a pre-defined intent mapped to a verification template by the ecosystem lead. Recommended for standardized, reusable verification flows. | | [Create Presentation Request](#create-presentation-request) | Directly specify the DCQL query and configuration without any template or intent. Useful for custom or ad-hoc verification scenarios. | ### Intent-Based Verification Presentation **`POST`** `/v1/orgs/{orgId}/oid4vp/intent-based-verification-presentation` Creates a VP request using a pre-configured intent. An intent is defined by the ecosystem lead and mapped to a specific verification template. The mapping may be global (shared across organizations) or organization-specific depending on the use case. #### Path Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------------------ | | `orgId` | string | The unique identifier of the organization. | #### Query Parameters | Parameter | Type | Required | Description | | ------------- | ------ | -------- | --------------------------------------------------------------------------------------- | | `verifierId` | string | Yes | The unique identifier of the verifier making the request. | | `ecosystemId` | string | Yes | The unique identifier of the ecosystem. Used to resolve the intent-to-template mapping. | #### Request Body **Content-Type:** `application/json` | Field | Type | Required | Description | | ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `intent` | string | Yes | The intent key defined by the ecosystem lead (e.g. `"kyc-intent"`). Resolved to a specific verification template via the ecosystem's intent-to-template mapping. | | `responseMode` | string | Yes | Defines how the holder's wallet should return the VP response. See [Response Modes](#response-modes) below. | | `requestSigner` | object | Yes | Configuration for signing the VP request. See [Request Signer Object](#request-signer-object) below. | | `expectedOrigins` | array | No | Array of allowed origin URLs. Required when `responseMode` is `dc_api` or `dc_api.jwt`. See [Expected Origins](#expected-origins) below. | #### Sample Request Payload ```json { "intent": "kyc-intent", "responseMode": "direct_post.jwt", "requestSigner": { "method": "DID", "clientIdPrefix": "x509_hash" }, "expectedOrigins": [ "https://example.com" ] } ``` ### Create Presentation Request **`POST`** `/v1/orgs/{orgId}/oid4vp/presentation` Creates a VP request directly using a specified DCQL query and configuration, without requiring an intent or a pre-built verification template. This provides full flexibility for custom or ad-hoc verification scenarios. #### Path Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------------------ | | `orgId` | string | The unique identifier of the organization. | #### Query Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------------------- | | `verifierId` | string | Yes | The unique identifier of the verifier making the request. | #### Request Body **Content-Type:** `application/json` | Field | Type | Required | Description | | ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `requestSigner` | object | Yes | Configuration for signing the VP request. See [Request Signer Object](#request-signer-object) below. | | `dcql` | object | Yes | The DCQL query defining which credentials and claims are required from the holder. Follows the same structure as `templateJson.dcql.query` in the [Create Verification Template API](broken://pages/732debebf12c3dc64d3aaa190ae60408fb674178). | | `responseMode` | string | Yes | Defines how the holder's wallet should return the VP response. See [Response Modes](#response-modes) below. | | `expectedOrigins` | array | No | Array of allowed origin URLs. Required when `responseMode` is `dc_api` or `dc_api.jwt`. See [Expected Origins](#expected-origins) below. | #### Sample Request Payload ```json { "requestSigner": { "method": "DID", "clientIdPrefix": "x509_hash" }, "dcql": {}, "responseMode": "direct_post.jwt", "expectedOrigins": [ "https://example.com" ] } ``` ### Shared Field Reference #### Response Modes The `responseMode` field controls how the holder's wallet submits the VP response back to the verifier. | Value | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------ | | `direct_post` | The wallet posts the VP response directly to the verifier's endpoint in plain form. | | `direct_post.jwt` | The wallet posts the VP response directly to the verifier's endpoint, signed as a JWT. | | `dc_api` | The VP response is returned via the Digital Credentials API. `expectedOrigins` is required. | | `dc_api.jwt` | The VP response is returned via the Digital Credentials API, signed as a JWT. `expectedOrigins` is required. | #### Request Signer Object Defines how the VP request itself is signed before being sent to the holder's wallet. | Field | Type | Required | Description | | ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `method` | string | Yes | The signing method for the VP request. See [Signer Methods](#signer-methods) below. | | `clientIdPrefix` | string | No | Applicable only for X.509-based methods. Specifies the client ID prefix format. See [Client ID Prefix](#client-id-prefix) below. | **Signer Methods** | Value | Description | | -------------- | ---------------------------------------------------------------------- | | `DID` | Signs the VP request using a Decentralized Identifier (DID). | | `X509_P256` | Signs the VP request using an X.509 certificate with P-256 key type. | | `X509_ED25519` | Signs the VP request using an X.509 certificate with Ed25519 key type. | **Client ID Prefix** Only applicable when `method` is `X509_P256` or `X509_ED25519`. | Value | Description | | -------------- | ---------------------------------------------------------------------------------------------------- | | `x509_san_dns` | The client ID is derived from the Subject Alternative Name (SAN) DNS entry of the X.509 certificate. | | `x509_hash` | The client ID is derived from a hash of the X.509 certificate. | #### Expected Origins `expectedOrigins` is an array of origin URLs (e.g. `["https://example.com"]`) that are permitted to receive the VP response when using the Digital Credentials API response modes (`dc_api` or `dc_api.jwt`). `expectedOrigins` must be specified to ensure the VP response is only accepted from trusted web origins. * **Required** when `responseMode` is `dc_api` or `dc_api.jwt`. * **Not applicable** for `direct_post` or `direct_post.jwt` modes. #### Notes * **Intent resolution:** An intent may be mapped globally across all organizations in an ecosystem, or scoped to a specific organization. The `ecosystemId` query parameter determines the resolution scope. * `clientIdPrefix` is only relevant for X.509-based `method` values (`X509_P256`, `X509_ED25519`). It has no effect when `method` is `DID`. * When using `dc_api` or `dc_api.jwt` response modes, `expectedOrigins` must be specified to ensure the VP response is only accepted from trusted web origins. *** ## OID4VP Verifier Presentation Status APIs Two APIs are available for retrieving the status and details of a verification session after a presentation request has been created. | API | Use Case | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | [Get Verifier Presentation](#get-verifier-presentation) | Retrieves the record details and current status of one or all presentation sessions for an organization. | | [Get Verifier Presentation Response](#get-verifier-presentation-response) | Retrieves the actual VP response data submitted by the holder. Only available once the session status is `ResponseVerified`. | ### Get Verifier Presentation **`GET`** `/v1/orgs/{orgId}/oid4vp/verifier-presentation` Retrieves details of all OID4VP verifier presentations or a single presentation by its ID for the specified organization. Returns the record details and current status of the session — it does **not** include the actual presentation data received from the holder. #### Path Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------ | | `orgId` | string | Yes | The unique identifier of the organization. | #### Query Parameters | Parameter | Type | Required | Description | | ------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- | | `publicVerifierId` | string | No | Public identifier of the verifier. Used to filter presentations by a specific verifier. | | `payloadState` | string | No | Opaque payload state value set by the client or verifier. Used to correlate sessions. | | `state` | string | No | Filter by the current presentation session state. See [Presentation States](#presentation-states) below. | | `authorizationRequestUri` | string | No | The authorization request URI associated with the session (if present). | | `authorizationRequestId` | string | No | The public ID of the authorization request. | | `nonce` | string | No | Nonce value associated with the presentation session. | | `id` | string | No | Optional ID to target and retrieve a specific presentation record. | #### Presentation States The `state` query parameter can be used to filter sessions by their current status in the verification lifecycle. | Value | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RequestCreated` | The VP request has been created but not yet scanned or accepted by the holder. | | `RequestUriRetrieved` | The holder's wallet has received the VP request. | | `ResponseVerified` | The VP response has been successfully verified. Presentation data is now accessible via the [Get Verifier Presentation Response](#get-verifier-presentation-response) API. | | `Error` | The verification session failed. | ### Get Verifier Presentation Response **`GET`** `/v1/orgs/{orgId}/oid4vp/verifier-presentation-response` Retrieves the actual Verifiable Presentation data submitted by the holder and received at the verifier agent. **This API is only available when the session status is `ResponseVerified`.** Calling it before that state will give error and not return presentation data. #### Path Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------ | | `orgId` | string | Yes | The unique identifier of the organization. | #### Query Parameters | Parameter | Type | Required | Description | | ---------------------------- | ------ | -------- | --------------------------------------------------------------------------------------- | | `verificationPresentationId` | string | Yes | The ID of the verification presentation session whose response data is to be retrieved. | #### Notes * **Use the correct API for the right stage:** Use [Get Verifier Presentation](#get-verifier-presentation) to poll the session status during the verification flow. Only call [Get Verifier Presentation Response](#get-verifier-presentation-response) once the session state is `ResponseVerified`. * The `id` query parameter on the Get Verifier Presentation API can be used to fetch a single specific session record instead of listing all sessions. * The `authorizationRequestId` is shared across session from verifier to holder so we treat it as sessionId/threadId in any functional usecases. *** ## OID4VP Verify Authorization Response API(DC API flow) ### Verify Authorization Response **`POST`** `/v1/orgs/{orgId}/oid4vp/verify-authorization-response` Submits the authorization response received on the browser back to the verifier system to update the associated verification session. This API is specific to the **DC API flow** (`dc_api` and `dc_api.jwt` response modes), where the holder's wallet returns the Verifiable Presentation directly to the browser rather than posting it to the verifier's endpoint. The verifier backend receives the browser-side `authorizationResponse` object and forwards it via this API. The agent then verifies the presentation data and updates the verification session state accordingly. #### Path Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------------------ | | `orgId` | string | The unique identifier of the organization. | #### Request Body **Content-Type:** `application/json` | Field | Type | Required | Description | | ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `verificationSessionId` | string | Yes | The ID of the verification session to update. This links the browser-received response to the correct pending session. | | `authorizationResponse` | object | Yes | The raw authorization response object received on the browser from the Digital Credentials API. Pass this object directly without modification. See [Authorization Response](#authorization-response-object) below. | | `origin` | string | Yes | The origin of the browser page that received the authorization response (e.g. `"https://example.com"`). Must match one of the `expectedOrigins` configured in the presentation request. | ### Authorization Response Object The `authorizationResponse` is the raw object returned by the Digital Credentials API on the browser. It should be forwarded to this API as-is, without any transformation. Its structure depends on the credential format and response mode used in the original presentation request. An example for a `dc_api.jwt` flow with an mdoc credential: ```json "authorizationResponse": { "id_token": { "Passport": [ "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ] } } ``` | Field | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------ | | `id_token` | object | Map of credential identifier to an array of JWT tokens representing the holder's Verifiable Presentation response. | #### Sample Request Payload ```json { "verificationSessionId": "93e156ca-a6b9-46ea-913d-f499be167d02", "authorizationResponse": { "id_token": { "Passport": [ "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tL2F1dGgvdjEvcmVhbG0tY3JlZGVibCIsInN1YiI6IjEyMzQ1Njc4OTAiLCJhdWQiOiJhdXRoLWNlbnRlci1pZCIsImV4cCI6MTY5ODAwMDAwMCwiaWF0IjoxNjk3OTk2NDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" ] } }, "origin": "https://example.com" } ``` #### Notes * The `authorizationResponse` object must be passed exactly as received from the browser's Digital Credentials API. Do not modify or re-encode the object before forwarding it. * On success, the agent verifies the presentation data and transitions the verification session state to `ResponseVerified`. The verified presentation data can then be retrieved via the [Get Verifier Presentation Response API](#get-verifier-presentation-response). ```mermaid sequenceDiagram title OpenID4VP Proof Presentation Flow participant VS as Verifier Service participant CR as CREDEBL participant VA as Verifier Agent participant MB as Mobile App / Browser Note over VS,MB: Phase 1 — Verification Session Request VS->>CR: Create verification session request CR->>VA: Initiate verification session Note over VA: Create OID4VP request VA-->>CR: Return OID4VP request URL CR-->>VS: Return OID4VP request URL Note over VS,MB: Phase 2 — User Interaction & Proof Submission VS->>MB: Render OID4VP request (URL / QR / deep link / DCAPI) MB->>VA: Submit VP (proof response) Note over VA: Verify proof credentials Note over VS,MB: Phase 3 — Webhook Callbacks & State Update VA-->>CR: Webhook: proof.state_changed CR-->>VS: Webhook: proof verified / error Note over VS: Update request state Note over VS: Final state: ResponseVerified / Error / RequestCreated ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.credebl.id/docs/references/platform-apis/oid4vc-apis/openid-for-verifiable-presentation-apis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.