#Isolated Flow

Endpoint: POST /wallet/{walletId}/credentials/present/preview | API Reference

#Example Request

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/preview \
  -H 'Content-Type: application/json' \
  -d '{
    "requestUrl": "openid4vp://authorize?client_id=x509_san_dns%3Averifier.example.org&request_uri=http%3A%2F%2Flocalhost%3A7004%2Fopenid4vc%2Frequest%2Fabc123"
  }'

Path Parameters

• walletId: String (required) - The wallet handling the presentation. See how to obtain it.

Body Parameters

• requestUrl: String (required) - The OID4VP authorization request URL.
• keyId: String (optional) - Signing key used for wallet capability advertisement and request validation during preview. Defaults to the wallet's default signing key. The Ready response echoes this back as keyId — pass the same value to Build the VP Token so preview and build agree on key capabilities (e.g. supported algorithms).

#Example Response

{
  "authorizationRequest": {
    "nonce": "n-0S6_WzA2Mj",
    "client_id": "x509_san_dns:verifier.example.org",
    "response_uri": "http://localhost:7004/openid4vc/response",
    "dcql_query": {
      "credentials": [
        {
          "id": "identity_credential",
          "format": "dc+sd-jwt",
          "claims": [
            { "path": ["given_name"] },
            { "path": ["family_name"] }
          ]
        }
      ]
    }
  },
  "valid": true,
  "keyId": "6ba7b810-9dad-11d1-80b4-preview-key",
  "clientId": "x509_san_dns:verifier.example.org",
  "verifier": {
    "name": "Example Verifier",
    "locale": "en-US",
    "logoUri": "https://verifier.example.org/logo.png",
    "clientUri": "https://verifier.example.org",
    "policyUri": null,
    "termsOfServiceUri": null
  },
  "responseUri": "http://localhost:7004/openid4vc/response",
  "state": "af0ifjsldkj",
  "nonce": "n-0S6_WzA2Mj",
  "responseEncryption": {
    "required": false
  },
  "transactionData": [],
  "credentialOptions": [
    {
      "queryId": "identity_credential",
      "credentialId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "multiple": false,
      "format": "dc+sd-jwt",
      "issuer": "http://localhost:7005/openid4vci",
      "subject": "did:key:z6Mk…",
      "label": null,
      "credentialData": {
        "given_name": "Ada",
        "family_name": "Lovelace",
        "vct": "https://issuer.example.com/identity_credential"
      },
      "disclosures": [
        {
          "path": "given_name",
          "name": "given_name",
          "value": "Ada",
          "selectivelyDisclosable": true,
          "required": true,
          "selectable": false
        },
        {
          "path": "family_name",
          "name": "family_name",
          "value": "Lovelace",
          "selectivelyDisclosable": true,
          "required": false,
          "selectable": true
        }
      ]
    }
  ],
  "credentialRequirements": [],
  "error": null
}

Response Fields

• authorizationRequest: Object - Resolved authorization request for display / technical details only.
• valid: Boolean - Whether the request passed wallet validation. When false, inspect error and optionally reject with that error.
• keyId: String (Ready only) - Signing key the preview used for wallet capability advertisement and validation. Pass this back as keyId to Build the VP Token so preview and build stay consistent.
• clientId: String - The verifier's client identifier.
• verifier: Object (optional) - Localized verifier display metadata from client_metadata (name, locale, logoUri, clientUri, policyUri, termsOfServiceUri). Supplied by the verifier — not evidence of trust on its own.
• responseUri / state / nonce: Request metadata projected for the UI.
• responseEncryption: Object - Whether response encryption is required and related algorithms/keys when present.
• transactionData: Array - Decoded transaction_data items attached to the request (type, credentialQueryIds, rawJson, details). Types must be registered in transaction-data-profiles.conf; discover them via GET /transaction-data-profiles.
• credentialOptions: Array - Wallet credentials that satisfy a DCQL credential query. Each entry includes:
  • queryId / credentialId — DCQL query id and wallet credential id (use these in build selections).
  • multiple / format / issuer / subject / label / credentialData — display and matching context.
  • disclosures — claims that may be shared (path, name, value, selectivelyDisclosable, required, selectable).
• credentialRequirements: Array - When DCQL credential sets apply: each item has options (a list of query-id combinations); at least one combination must be satisfied.
• error: Object (optional) - When valid is false: code and optional message.

Endpoint: POST /wallet/{walletId}/credentials/present/build-vp-token | API Reference

#Example Request (after preview)

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/build-vp-token \
  -H 'Content-Type: application/json' \
  -d '{
    "requestUrl": "openid4vp://authorize?client_id=x509_san_dns%3Averifier.example.org&request_uri=http%3A%2F%2Flocalhost%3A7004%2Fopenid4vc%2Frequest%2Fabc123",
    "selectedCredentialOptions": [
      {
        "queryId": "identity_credential",
        "credentialId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
      }
    ],
    "selectedDisclosureOptions": [
      {
        "queryId": "identity_credential",
        "credentialId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "path": "family_name"
      }
    ]
  }'

#Example Request (legacy IDs after match)

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/build-vp-token \
  -H 'Content-Type: application/json' \
  -d '{
    "requestUrl": "openid4vp://authorize?client_id=x509_san_dns%3Averifier.example.org&request_uri=http%3A%2F%2Flocalhost%3A7004%2Fopenid4vc%2Frequest%2Fabc123",
    "selectedCredentialIds": {
      "identity_credential": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
    }
  }'

Path Parameters

• walletId: String (required) - The wallet holding the selected credentials.

Body Parameters

• requestUrl: String (required) - The same OID4VP authorization request URL used for Preview (or Resolve the Request). Re-resolved and revalidated on every call.
• selectedCredentialOptions: Array (optional) - Preferred for consent UIs. List of { queryId, credentialId } from credentialOptions. When non-empty, takes precedence over selectedCredentialIds.
• selectedDisclosureOptions: Array (optional) - Selectively disclosable claim paths to include: { queryId, credentialId, path } (paths from that option's disclosures). Omit to keep the default disclosure set for the selection (required claims plus matcher defaults). When provided as an empty list, optional selectively disclosable claims are not added beyond what the protocol still requires.
• selectedCredentialIds: Object (optional) - Legacy map of DCQL query ID to wallet credential IDs (from Match from the wallet stores). Used when selectedCredentialOptions is empty.
• key: Object (optional) - Inline key used to sign the VP token. Takes precedence over keyId.
• keyId: String (optional) - Key used to sign the VP token. Defaults to the wallet's default key. When you drove the flow through Preview with a specific keyId, pass the same value (returned as keyId in the Ready response) here so preview and build use the same signing key.
• did: String (optional) - DID for holder binding. Defaults to the wallet's default DID.

#Example Response

{
  "vpToken": "{\"identity_credential\":\"eyJhbGciOiJFUzI1NiIs...\"}",
  "idToken": null
}

Response Fields

• vpToken: String - Serialized vp_token JSON string.
• idToken: String (optional) - Self-issued ID token for SIOPv2 flows, when one is required.

Endpoint: POST /wallet/{walletId}/credentials/present/send-response | API Reference

#Example Request

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/send-response \
  -H 'Content-Type: application/json' \
  -d '{
    "requestUrl": "openid4vp://authorize?client_id=x509_san_dns%3Averifier.example.org&request_uri=http%3A%2F%2Flocalhost%3A7004%2Fopenid4vc%2Frequest%2Fabc123",
    "vpToken": "{\"identity_credential\":\"eyJhbGciOiJFUzI1NiIs...\"}",
    "idToken": null
  }'

Body Parameters

• requestUrl: String (required) - The same OID4VP authorization request URL used for Preview. Re-resolved and revalidated on every call.
• vpToken: String (required) - The vpToken returned by Build the VP Token.
• idToken: String (optional) - The idToken returned by Build the VP Token, when present.

#Example Response

Returns the same shape as the full presentation flow — transmission_success, verifier_response, and optionally redirect_to.

Endpoint: POST /wallet/{walletId}/credentials/present/reject | API Reference

#Example Request

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/reject \
  -H 'Content-Type: application/json' \
  -d '{
    "requestUrl": "openid4vp://authorize?client_id=x509_san_dns%3Averifier.example.org&request_uri=http%3A%2F%2Flocalhost%3A7004%2Fopenid4vc%2Frequest%2Fabc123",
    "errorCode": "access_denied",
    "errorDescription": "User declined"
  }'

Body Parameters

• requestUrl: String (required) - The same OID4VP authorization request URL used for preview.
• errorCode: String (optional) - OpenID4VP error code. Defaults to access_denied.
• errorDescription: String (optional) - Human-readable description sent to the verifier.

#Example Response

Returns the same WalletPresentResult shape as Send the Response (for example transmission_success and any redirect URL produced by the reject handling).

Endpoint: POST /wallet/{walletId}/credentials/present/resolve-request | API Reference

#Example Request

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/resolve-request \
  -H 'Content-Type: application/json' \
  -d '{
    "requestUrl": "openid4vp://authorize?client_id=x509_san_dns%3Averifier.example.org&request_uri=http%3A%2F%2Flocalhost%3A7004%2Fopenid4vc%2Frequest%2Fabc123"
  }'

Path Parameters

• walletId: String (required) - The wallet handling the presentation. See how to obtain it.

Body Parameters

• requestUrl: String (required) - The OID4VP authorization request URL.

#Example Response

{
  "authorizationRequest": {
    "nonce": "n-0S6_WzA2Mj",
    "client_id": "x509_san_dns:verifier.example.org",
    "response_uri": "http://localhost:7004/openid4vc/response",
    "dcql_query": {
      "credentials": [
        {
          "id": "identity_credential",
          "format": "dc+sd-jwt"
        }
      ]
    }
  },
  "nonce": "n-0S6_WzA2Mj",
  "clientId": "x509_san_dns:verifier.example.org",
  "responseUri": "http://localhost:7004/openid4vc/response",
  "hasRequestUri": true,
  "dcqlQuery": {
    "credentials": [
      {
        "id": "identity_credential",
        "format": "dc+sd-jwt"
      }
    ]
  }
}

Response Fields

• authorizationRequest: Object - Resolved authorization request for inspection / display.
• nonce: String - The verifier's nonce, which the presentation must be bound to.
• clientId: String - The verifier's client identifier.
• responseUri: String - Where the presentation will be submitted.
• hasRequestUri: Boolean - Whether the request was fetched from a request_uri (vs supplied inline).
• dcqlQuery: Object - The verifier's DCQL query, ready to pass to Match from the Wallet Stores or Match Inline Credentials.

Endpoint: POST /wallet/{walletId}/credentials/present/match-credentials-from-store | API Reference

#Example Request

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/match-credentials-from-store \
  -H 'Content-Type: application/json' \
  -d '{
    "dcqlQuery": {
      "credentials": [
        {
          "id": "identity_credential",
          "format": "dc+sd-jwt",
          "meta": { "vct_values": ["https://issuer.example.com/identity_credential"] },
          "claims": [
            { "path": ["given_name"] },
            { "path": ["family_name"] }
          ]
        }
      ]
    }
  }'

Path Parameters

• walletId: String (required) - The wallet whose stored credentials are matched.

Body Parameters

• dcqlQuery: Object (required) - The verifier's DCQL query returned by Resolve the Request.

#Example Response

{
  "matchedQueryIds": ["credential_1"],
  "matchCount": 2,
  "matchedCredentialIds": {
    "credential_1": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
  }
}

Response Fields

• matchedQueryIds: String - The DCQL credential-query IDs that were satisfied.
• matchCount: Number - Total number of matching credentials.
• matchedCredentialIds: Object - Map of DCQL query ID to wallet-assigned credential IDs. Use these IDs with Build the VP Token via selectedCredentialIds.

After the user consents, complete the manual presentation with Build the VP Token and Send the Response, or use the full-flow endpoint to match and submit in one call.

Endpoint: POST /wallet/{walletId}/credentials/present/match-credentials | API Reference

#Example Request

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/match-credentials \
  -H 'Content-Type: application/json' \
  -d '{
    "dcqlQuery": { "credentials": [ { "id": "credential_1", "format": "dc+sd-jwt", "meta": { "vct_values": ["https://issuer.example.com/identity_credential"] }, "claims": [ { "path": ["given_name"] } ] } ] },
    "credentials": [
      { "id": "inline-1", "credential": { "type": "vc-sd_jwt", "dmtype": "sdjwtvcdm", "signedWithDisclosures": "eyJ...~WyJ...~", "credentialData": { "vct": "https://issuer.example.com/identity_credential", "given_name": "John" } } }
    ]
  }'

Body Parameters

• dcqlQuery: Object (required) - The DCQL query to match against.
• credentials: Array (required) - The credentials to match. Each entry has an id (your own label, echoed back in the result) and a credential: the credential in the wallet's own JSON representation — not a raw credential string. Its type field marks the format (vc-sd_jwt, vc-w3c_2, or mso_mdoc); the shape beyond that is internal to each format (for vc-sd_jwt: dmtype, signedWithDisclosures, credentialData, and — only when the credential has selectively disclosable claims — disclosables, disclosures, and originalCredentialData). Don't hand-construct this object — the simplest and most reliable way to get one in the right shape is to copy the credential object from a GET /wallet/{walletId}/credentials/{id} response.

#Example Response

Returns the same MatchCredentialsResult shape as Match from the wallet stores.

Endpoint: POST /wallet/{walletId}/credentials/present/isolated | API Reference

#Example Request

curl -X POST http://localhost:7006/wallet/{walletId}/credentials/present/isolated \
  -H 'Content-Type: application/json' \
  -d '{
    "requestUrl": "openid4vp://authorize?client_id=verifier2&request_uri=http%3A%2F%2Flocalhost%3A7004%2Fverification-session%2Fabc123%2Frequest",
    "credentials": [
      { "id": "inline-1", "credential": { "type": "vc-sd_jwt", "dmtype": "sdjwtvcdm", "signedWithDisclosures": "eyJ...~WyJ...~", "credentialData": { "vct": "https://issuer.example.com/identity_credential", "given_name": "John" } } }
    ],
    "keyId": "my-holder-key"
  }'

Body Parameters

• requestUrl: String (required) - The OID4VP authorization request URL.
• credentials: Array (required) - The credentials to present. Each entry has an id and a credential: the credential in the wallet's own JSON representation (same field structure as Match Inline Credentials above), not a raw credential string. Unlike matching, actually building and signing a presentation needs the complete object — copy it as-is from a GET /wallet/{walletId}/credentials/{id} response rather than trimming fields; for an SD-JWT VC with selectively disclosable claims this includes signature, signed, disclosables, disclosures, and originalCredentialData alongside the fields shown above.
• keyId: String (optional) - Key used to sign the presentation. Must be the holder key the inline credential is bound to. Defaults to the wallet's default key.
• did: String (optional) - DID for the presenter identity. Defaults to the wallet's default DID.

#Example Response

Returns the same shape as the full presentation flow — transmission_success, verifier_response, and optionally redirect_to.