Update presentation definition

PUT 
/v2/config/digital-wallet/openid/sdjwt/presentation-definition/:presentationDefinitionId

Updates a presentation definition. The update is partial: a property that you leave out keeps its stored value. The server checks each rule that the change touches against the result, with the same rules as the create operation.

The server keeps the stored label when you send no label, or a label that has one character or less after the spaces are removed. A new label must be unique in the organisation and must not be a label that an extension reserves, for example 'Age Verification', 'Document Signing' or 'Know-Your-Customer (KYC)'.

Rules that the server applies:

• You cannot update a presentation definition that an extension uses.
• dcqlQuery replaces the stored DCQL query. Send the full query, because the server does not merge it with the stored one.
• listedClaims replaces the stored list, and {} clears it. Every key must be the id of a credential query in dcqlQuery, and every claim needs a non-empty path.
• A sent cryptographicKeyFormat or cryptographicKeyIdentifier replaces the stored signing key, and the server checks it as on create.
• dcApiRequestType is allowed only when the effective responseMode is dc_api or dc_api.jwt. If the body has no responseMode, the server uses the responseMode of the stored record.
• expectedOrigins is mandatory when the effective request type is signed. The server accepts the stored expectedOrigins when the body has none.
• excludeVerifierDisplayMetadata changes only when you send true or false.

Request

Path Parameters

presentationDefinitionId stringrequired

Unique identifier of the presentation definition that specifies the credential and claims requirements for OpenID4VP verification.

application/json

Body

required

Properties of the presentation definition to change. A property that you leave out keeps its stored value.

label string

Possible values: <= 100 characters

New human-readable label of the presentation definition. The server keeps the stored label when you send a label that has one character or less after the spaces are removed. The label must be unique in the organisation. Labels that extensions reserve are refused.

dcqlQuery object

New Digital Credentials Query Language (DCQL) query. It holds a credentials array, and every entry needs an id, a format and a meta object. The format sets the meta key: mso_mdoc takes doctype_value, dc+sd-jwt takes vct_values, and jwt_vc_json takes type_values. The vc+sd-jwt, vp+sd-jwt and jwt_vc formats take "meta": {}. Each entry of credential_sets needs a non-empty options array.

This query replaces the stored query. The server keeps the stored query when you send no dcqlQuery.

property name* any

New Digital Credentials Query Language (DCQL) query. It holds a credentials array, and every entry needs an id, a format and a meta object. The format sets the meta key: mso_mdoc takes doctype_value, dc+sd-jwt takes vct_values, and jwt_vc_json takes type_values. The vc+sd-jwt, vp+sd-jwt and jwt_vc formats take "meta": {}. Each entry of credential_sets needs a non-empty options array.

This query replaces the stored query. The server keeps the stored query when you send no dcqlQuery.

listedClaims object
Not needed when you use the API: leave a claim out of claims of the query and the verifier does not ask for it. The dashboard sends this list so that its builder can show the same data attributes again, ticked or unticked, when the presentation definition is edited. It holds, per credential query (keyed by its id in dcqlQuery), the attributes the dashboard shows, in order, as claim objects with a path as in claims of the query. A listed claim that is in claims of the query is ticked; one that is not is unticked, and the verification request does not ask for it.
This list replaces the stored one. The server keeps the stored list when you send no listedClaims; send {} to clear it. Send it together with dcqlQuery: every key must be the id of a credential query in the query, and every claim needs a non-empty path.
property name* object[]
Array [
path undefined[]required
Pointer to the claim inside the credential, as in claims of the credential query.
]
transactionDataDefinitionType string

Possible values: [payment_data, payment, login_risk_transaction, login_risk_transaction_non_ts12, account_access, emandate, data_agreement_record, data_disclosure_agreement_record, qes_data]

New type of transaction data that the verification request binds. Read GET /v2/config/digital-wallet/openid/sdjwt/transaction-data-definitions for the schema of each type.

transactionDataCredentialIds string[]

New identifiers of the credential queries that the transaction data binds to. Each value must be an id in dcqlQuery.credentials.

version string

Possible values: [version_01, iso18013_7_annex_c]

New OpenID4VP version of the Authorization Request.

responseType string

Possible values: [vp_token, device_response]

New OAuth 2.0 response type. version_01 accepts only vp_token, and iso18013_7_annex_c accepts only device_response.

clientIdScheme string

Possible values: [redirect_uri, did, verifier_attestation, x509_san_dns, x509_hash]

New client ID scheme of the Authorization Request. The server keeps the stored scheme when you send no value. x509_hash and x509_san_dns need an x509 key, and did needs a did:key key. redirect_uri gives an unsigned request outside the DC API response modes.

cryptographicKeyFormat string

Possible values: [did:key, x509]

New format of the signing key. x509 needs a key with a certificate chain.

cryptographicKeyIdentifier string

Key identifier of the new key that signs the Authorization Request.

scope string

New OAuth 2.0 scope value for a scope-based presentation request. The scope must be unique in the organisation.

directPostRedirectUri string

New absolute URI that the wallet opens after it posts the Authorization Response. For the direct_post and direct_post.jwt response modes.

responseMode string

Possible values: [direct_post, direct_post.jwt, dc_api, dc_api.jwt]

New response mode. It sets how the wallet of the holder delivers the Authorization Response.

dcApiRequestType string

Possible values: [signed, unsigned]

New DC API request signing type. signed makes the verifier sign the Authorization Request. unsigned gives no verifier authentication. Use signed for live use.

expectedOrigins string[]

New list of web origins that the wallet accepts for a signed DC API request. The wallet compares these values with the actual origin to find a replay.

encryptedResponseEncValuesSupported string[]

Possible values: [A128CBC-HS256, A128GCM, A256GCM]

New JWE content encryption algorithms for a direct_post.jwt Authorization Response.

excludeVerifierDisplayMetadata boolean

true leaves the display metadata of the verifier out of the Authorization Request. The server keeps the stored value when you send no value.

Responses

200

The server updated the presentation definition.

Response Headers

application/json

Schema

Schema

presentationDefinition objectrequired

id string

Identifier of the presentation definition. It holds the same value as presentationDefinitionId.

openIdOrganisationId string

Identifier of the digital wallet of the organisation that owns this presentation definition.

presentationDefinitionId string

Unique identifier that the server gives to the presentation definition. Use this identifier in a verification request and in the path of the read, update and delete endpoints.

label string

Human-readable label that gives the purpose of this presentation definition, for example 'Verify Portable Document A1'. The dashboard shows this label.

dcqlQuery object

Digital Credentials Query Language (DCQL) query that gives the credentials and the claims that the verifier asks from the holder.

The query holds a credentials array. Each entry has an id, a format and a format-specific meta object: doctype_value for mso_mdoc, vct_values for dc+sd-jwt, and type_values for jwt_vc_json. An entry can also hold claims, claim_sets, require_cryptographic_holder_binding, multiple and trusted_authorities. A top-level credential_sets array can group the credential queries.

The server leaves this property out when the presentation definition has no DCQL query.

property name* any

Digital Credentials Query Language (DCQL) query that gives the credentials and the claims that the verifier asks from the holder.

The query holds a credentials array. Each entry has an id, a format and a format-specific meta object: doctype_value for mso_mdoc, vct_values for dc+sd-jwt, and type_values for jwt_vc_json. An entry can also hold claims, claim_sets, require_cryptographic_holder_binding, multiple and trusted_authorities. A top-level credential_sets array can group the credential queries.

The server leaves this property out when the presentation definition has no DCQL query.

listedClaims object

Not needed when you use the API: leave a claim out of claims of the query and the verifier does not ask for it. The dashboard sends this list so that its builder can show the same data attributes again, ticked or unticked, when the presentation definition is edited. It holds, per credential query (keyed by its id in dcqlQuery), the attributes the dashboard shows, in order, as claim objects with a path as in claims of the query. A listed claim that is in claims of the query is ticked; one that is not is unticked, and the verification request does not ask for it.

The server leaves this property out when the presentation definition has no list, as a definition created through the API without it.

property name* object[]

Array [

path undefined[]

Pointer to the claim inside the credential, as in claims of the credential query.

]

transactionDataDefinitionType string

Possible values: [``, payment_data, payment, login_risk_transaction, login_risk_transaction_non_ts12, account_access, emandate, data_agreement_record, data_disclosure_agreement_record, qes_data]

Type of transaction data that the verification request binds. The holder must approve the transaction data before the wallet sends the presentation. The value selects the JSON Schema that the server uses to validate the transactionData of the verification request. Read GET /v2/config/digital-wallet/openid/sdjwt/transaction-data-definitions for the schema of each type.

The value is an empty string when the presentation definition binds no transaction data.

createdAt number

Unix timestamp, in seconds, of the moment that the server created this presentation definition.

updatedAt number

Unix timestamp, in seconds, of the moment that the server last changed this presentation definition.

version string

Possible values: [version_01, iso18013_7_annex_c]

OpenID for Verifiable Presentations (OpenID4VP) version of the Authorization Request. version_01 is OpenID4VP 1.0. iso18013_7_annex_c is the ISO 18013-7 Annex C profile, which asks for mDoc credentials over the Digital Credentials API.

cryptographicKeyIdentifier string

Key identifier of the key that signs the Authorization Request. When the create request names no key, this is the default key of the organisation. The value is an empty string when the request is not signed.

cryptographicKeyFormat string

Possible values: [did:key, x509]

Format of the signing key. It sets how the wallet of the holder resolves the identity of the verifier. The server leaves this property out when the request is not signed (clientIdScheme redirect_uri outside the DC API response modes).

scope string

OAuth 2.0 scope value for a scope-based presentation request. The value is an empty string when the presentation definition holds no scope.

responseType string

Possible values: [vp_token, device_response]

OAuth 2.0 response type of the Authorization Request. vp_token asks for a Verifiable Presentation. device_response asks for an ISO 18013-5 DeviceResponse and is only for iso18013_7_annex_c.

clientIdScheme string

Possible values: [redirect_uri, did, verifier_attestation, x509_san_dns, x509_hash]

Client ID scheme of the Authorization Request. It sets how the verifier identifies itself to the wallet of the holder. redirect_uri uses a redirect URI, did uses a DID, verifier_attestation uses a Verifier Attestation JWT, x509_san_dns uses the SAN DNS name of an X.509 certificate, and x509_hash uses the hash of an X.509 certificate. With the DC API response modes, redirect_uri is only a logical identifier and not a real redirect target. The server leaves this property out for iso18013_7_annex_c.

directPostRedirectUri string

URI that the wallet of the holder opens after it posts the Authorization Response. For the direct_post and direct_post.jwt response modes. The server leaves this property out when the presentation definition holds no URI.

responseMode string

Possible values: [direct_post, direct_post.jwt, dc_api, dc_api.jwt]

Response mode that sets how the wallet of the holder delivers the Authorization Response. Direct Post: direct_post posts the response over HTTP. direct_post.jwt posts the response as an encrypted JWT. DC API: dc_api uses the W3C Digital Credentials API and returns the response without JWE encryption. dc_api.jwt uses the Digital Credentials API and returns the response as a JWE.

dcApiRequestType string

Possible values: [signed, unsigned]

Signing type of the DC API request. Only for the dc_api and dc_api.jwt response modes. signed means that the verifier signs the Authorization Request. unsigned means that the verifier sends the request unsigned. The server leaves this property out when the presentation definition holds no value.

expectedOrigins string[]

Origins that the wallet accepts for a signed DC API request. The server leaves this property out when the presentation definition holds no origin.

encryptedResponseEncValuesSupported string[]

Possible values: [A128CBC-HS256, A128GCM, A256GCM]

JWE content encryption algorithms that the verifier accepts for the Authorization Response. It applies to the direct_post.jwt response mode; the dc_api.jwt flow ignores it and always advertises A128GCM and A256GCM.

The server leaves this property out when the presentation definition holds no algorithm.

systemManaged boolean

true when the platform owns this presentation definition. You cannot delete a system managed presentation definition.

extentionEnabled boolean

true when an extension uses this presentation definition. You cannot update such a presentation definition, and you cannot delete most of them. Note the spelling of this property name.

presentationDefinition objectrequired

Legacy credential requirements of a presentation definition that an older OpenID4VP version created. The value is null for every presentation definition that uses dcqlQuery.

property name* any

Legacy credential requirements of a presentation definition that an older OpenID4VP version created. The value is null for every presentation definition that uses dcqlQuery.

transactionDataCredentialIds string[]

Identifiers of the credential queries that the transaction data binds to. The server leaves this property out when the presentation definition holds no value.

excludeVerifierDisplayMetadata boolean

true when the Authorization Request leaves out the display metadata of the verifier (name, logo and description).

Example (from schema)

{
  "presentationDefinition": {
    "id": "string",
    "openIdOrganisationId": "string",
    "presentationDefinitionId": "string",
    "label": "string",
    "dcqlQuery": {},
    "listedClaims": {},
    "transactionDataDefinitionType": "",
    "createdAt": 0,
    "updatedAt": 0,
    "version": "version_01",
    "cryptographicKeyIdentifier": "string",
    "cryptographicKeyFormat": "did:key",
    "scope": "string",
    "responseType": "vp_token",
    "clientIdScheme": "redirect_uri",
    "directPostRedirectUri": "string",
    "responseMode": "direct_post",
    "dcApiRequestType": "signed",
    "expectedOrigins": [
      "string"
    ],
    "encryptedResponseEncValuesSupported": [
      "A128CBC-HS256"
    ],
    "systemManaged": true,
    "extentionEnabled": true,
    "presentationDefinition": {},
    "transactionDataCredentialIds": [
      "string"
    ],
    "excludeVerifierDisplayMetadata": true
  }
}

400

No presentation definition has the supplied presentationDefinitionId, an extension uses the presentation definition, the body is not valid JSON, label is in use or is a label that an extension reserves, the transport settings do not agree, the DCQL query is not valid, or the organisation has no deployed digital wallet.

Response Headers

application/json

Schema

Schema

errorCode integer
errorDescription string

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

401

Unauthorized

Response Headers

application/json

Schema

Schema

errorCode integer
errorDescription string

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

500

Internal server error

Response Headers

application/json

Schema

Schema

errorCode integer
errorDescription string

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

Loading...