Skip to main content

Create presentation definition

POST 
/v2/config/digital-wallet/openid/sdjwt/presentation-definition

Creates a presentation definition. The presentation definition gives the credential types and the claims that the verifier needs for an OpenID4VP verification.

Give the credential requirements as a Digital Credentials Query Language (DCQL) query in dcqlQuery. The verifier is OpenID4VP 1.0 and accepts DCQL queries only.

The presentation definition also holds the transport settings that every verification request inherits: responseMode, clientIdScheme, dcApiRequestType, expectedOrigins and encryptedResponseEncValuesSupported. Both Direct Post (direct_post, direct_post.jwt) and DC API (dc_api, dc_api.jwt) response modes are available.

Sign the request with an X.509 key: a key with a certificate chain, cryptographicKeyFormat x509 and clientIdScheme x509_hash (or x509_san_dns). When you leave out clientIdScheme, the server takes x509_hash for an x509 key, so the request is signed.

Rules that the server applies:

  • label, version and dcqlQuery are mandatory.
  • label must be 3 to 100 characters long and unique in the organisation. It must not be a label that an extension reserves, for example 'Age Verification', 'Document Signing' or 'Know-Your-Customer (KYC)'. The check ignores case.
  • version_01 accepts only the vp_token response type.
  • Each entry of dcqlQuery.credentials 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": {}. Any other key is refused.
  • claims and trusted_authorities must not be empty when you send them. claim_sets needs a non-empty claims array in the same credential query.
  • Each entry of dcqlQuery.credential_sets needs a non-empty options array.
  • clientIdScheme x509_hash and x509_san_dns need an x509 key, and x509_san_dns also needs a DNS name in the subject alternative names of the leaf certificate. did needs a did:key key.
  • With clientIdScheme redirect_uri outside the DC API response modes, the request is not signed: send no cryptographicKeyFormat and no cryptographicKeyIdentifier.
  • directPostRedirectUri must be an absolute URI. It applies to direct_post and direct_post.jwt.
  • encryptedResponseEncValuesSupported is mandatory when responseMode is direct_post.jwt, and supportCredentialEncryption must be true in the verifier global configuration.
  • dcApiRequestType is allowed only when responseMode is dc_api or dc_api.jwt.
  • expectedOrigins is mandatory when the request type is signed, and refused for an unsigned request. dc_api.jwt defaults to signed and dc_api defaults to unsigned.
  • transactionDataDefinitionType is mandatory when the DCQL query asks for a Payment Wallet Attestation, a QESAC credential or an SCA attestation. The query can hold only one such credential.
  • scope must be unique in the organisation.

The iso18013_7_annex_c version has more rules: responseType must be device_response, cryptographicKeyFormat must be x509, clientIdScheme and transactionDataDefinitionType must be absent, expectedOrigins must hold exactly one origin, every credential query must use mso_mdoc with a meta.doctype_value, a non-empty claims array and require_cryptographic_holder_binding set to true, every claim path must hold two elements, and credential_sets and claim_sets are not allowed.

Request​

Body

required

Label, credential requirements and transport settings of the new presentation definition.

    anyOf
    label stringrequired

    Possible values: >= 3 characters and <= 100 characters

    Human-readable label that gives the purpose of this presentation definition, for example 'Verify Portable Document A1'. The dashboard shows this label. The label must be 3 to 100 characters long and unique in the organisation. Labels that extensions reserve are refused, without regard to case, for example 'Age Verification', 'Document Signing', 'Know-Your-Customer (KYC)' and 'PID Credential Issuance'.

    dcqlQuery objectrequired

    Digital Credentials Query Language (DCQL) query that gives the credentials and the claims that the verifier asks from the holder. This is the only way to give the credential requirements.

    The query holds a credentials array. Each entry needs an id, a format and a meta object. The format controls which meta key the server accepts. Each 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.

    credentials object[]required

    Possible values: >= 1

    Credential queries. The wallet of the holder must satisfy every entry, unless credential_sets says otherwise.

  • Array [
    • id stringrequired

    Identifier of this credential query. credential_sets and the presentation response use this value. Use only letters, digits, _ and -, and make the value unique in the query. Do not use spaces. The server does not apply the character check to the iso18013_7_annex_c version.

    format stringrequired

    Possible values: [dc+sd-jwt, vc+sd-jwt, vp+sd-jwt, jwt_vc_json, jwt_vc, mso_mdoc]

    Credential format that the verifier accepts for this query.

    meta objectrequired

    Format-specific match rules. This property is mandatory. The format sets the key that meta must hold, and the server refuses any other key:

    • mso_mdoc - doctype_value.
    • dc+sd-jwt - vct_values.
    • jwt_vc_json - type_values.
    • vc+sd-jwt, vp+sd-jwt, jwt_vc - no key. Send "meta": {}.
    vct_values string[]

    Accepted vct values of the SD-JWT VC, as a non-empty array of strings. Use this property with the dc+sd-jwt format only.

    type_values array[]

    Accepted type sets of the credential, as a non-empty array. Each entry is a non-empty array of type names, and the credential must hold every type of at least one entry. Use this property with the jwt_vc_json format only.

    doctype_value string

    Accepted docType of the mDoc, for example org.iso.18013.5.1.mDL. Use this property with mso_mdoc only.

    property name* any

    Format-specific match rules. This property is mandatory. The format sets the key that meta must hold, and the server refuses any other key:

    • mso_mdoc - doctype_value.
    • dc+sd-jwt - vct_values.
    • jwt_vc_json - type_values.
    • vc+sd-jwt, vp+sd-jwt, jwt_vc - no key. Send "meta": {}.
    claims object[]

    Claims that the verifier asks for. Leave this property out to ask for the whole credential. When you send it, it must not be empty.

  • Array [
    • id string

    Identifier of this claim query. claim_sets uses this value. Give an id to every claim when you use claim_sets.

    path undefined[]

    Pointer to the claim inside the credential. For mso_mdoc the path holds exactly two strings: the namespace and the data element, for example ['org.iso.18013.5.1', 'family_name']. For the other formats each element is a property name, a non-negative array index, or null for every element of an array. For jwt_vc_json the path starts with a member of the credential, so a subject claim starts with credentialSubject.

    values undefined[]

    Values that the claim must hold: strings, integers or booleans. Leave this property out to accept every value.

  • ]
    • claim_sets array[]

    Alternative sets of claims. Each entry is an array of claim id values, and the wallet satisfies the first entry that it can. Send this property only together with a non-empty claims array.

    require_cryptographic_holder_binding boolean

    true when the credential must prove that the holder owns it.

    multiple boolean

    true when the wallet can return more than one credential for this query.

    trusted_authorities object[]

    Issuers that the verifier trusts for this query. When you send it, it must not be empty.

  • Array [
    • type string

    Type of the trust list, for example etsi_tl for an ETSI trusted list or aki for an authority key identifier.

    values string[]

    Identifiers of the trusted issuers, as a non-empty array of strings.

  • ]
  • ]
    • credential_sets object[]

    Groups of credential queries. Each entry gives the combinations of credential query identifiers that satisfy the request.

  • Array [
    • options array[]required

    Possible values: >= 1

    Accepted combinations. Each entry is an array of credential query identifiers. This property is mandatory, and it must hold at least one combination.

    required boolean

    true when the wallet must satisfy one of the options.

    purpose

    Reason why the verifier asks for this group of credentials. The server accepts a string, a number or an object here.

  • ]
    • property name* any

    Digital Credentials Query Language (DCQL) query that gives the credentials and the claims that the verifier asks from the holder. This is the only way to give the credential requirements.

    The query holds a credentials array. Each entry needs an id, a format and a meta object. The format controls which meta key the server accepts. Each 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.

    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.

    This property is mandatory when the DCQL query asks for a Payment Wallet Attestation, a QESAC credential or an SCA attestation.

    version stringrequired

    Possible values: [version_01, iso18013_7_annex_c]

    OpenID for Verifiable Presentations (OpenID4VP) version of the Authorization Request. This property is mandatory and has no default. 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. The server uses the default key of the organisation when you send no value. Do not send it when clientIdScheme is redirect_uri outside the DC API response modes: that 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. x509 needs a key with a certificate chain. When you send no value, the server takes the format that clientIdScheme needs, else x509 when the key has a certificate chain and did:key when it has none. iso18013_7_annex_c needs x509. Do not send it when clientIdScheme is redirect_uri outside the DC API response modes.

    scope string

    OAuth 2.0 scope value for a scope-based presentation request.

    responseType string

    Possible values: [vp_token, device_response]

    Default value: vp_token

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

    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.

    • x509_hash uses the hash of the X.509 certificate of the signing key, and x509_san_dns uses a DNS name in the subject alternative names of that certificate. Both need cryptographicKeyFormat x509.
    • did uses the DID of the signing key and needs cryptographicKeyFormat did:key.
    • verifier_attestation uses a Verifier Attestation JWT.
    • redirect_uri uses the response URI and gives an unsigned request outside the DC API response modes. Then send no cryptographicKeyFormat and no cryptographicKeyIdentifier. With the DC API response modes, redirect_uri is only a logical identifier.

    When you leave this property out on version_01, the server takes x509_hash for an x509 key and did for a did:key key, so the request is signed. Leave it out for iso18013_7_annex_c.

    directPostRedirectUri string

    Absolute URI that the wallet of the holder opens after it posts the Authorization Response, for example https://verifier.example.com/done or an app link such as myapp://done. For the direct_post and direct_post.jwt response modes. It has no meaning for the DC API response modes.

    responseMode string

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

    Default value: direct_post

    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 allowed when responseMode is dc_api or dc_api.jwt. signed makes the verifier sign the Authorization Request. unsigned gives no verifier authentication. The server treats a missing value as unsigned for dc_api and as signed for dc_api.jwt. Use signed for live use.

    expectedOrigins string[]

    Web origins (https://host[:port], no path) that the wallet accepts for a signed DC API request. The wallet compares these values with the actual origin to find a replay. Mandatory when the effective dcApiRequestType is signed. iso18013_7_annex_c needs exactly one origin. The server refuses this property for an unsigned request and outside the DC API response modes.

    encryptedResponseEncValuesSupported string[]

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

    JWE content encryption algorithms that the verifier accepts for the Authorization Response.

    This property is mandatory when responseMode is direct_post.jwt, and supportCredentialEncryption must be true in the verifier global configuration.

    The dc_api.jwt response mode ignores this property. That flow always advertises A128GCM and A256GCM, and encrypts with A256GCM.

    excludeVerifierDisplayMetadata boolean

    Default value: false

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

    transactionDataCredentialIds string[]

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

Responses​

The server created the presentation definition.

Response Headers
    Schema
      presentationDefinition objectrequired
      id stringrequired

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

      openIdOrganisationId stringrequired

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

      presentationDefinitionId stringrequired

      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 stringrequired

      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.

      transactionDataDefinitionType stringrequired

      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 numberrequired

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

      updatedAt numberrequired

      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 stringrequired

      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 stringrequired

      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 stringrequired

      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 booleanrequired

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

      extentionEnabled booleanrequired

      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 booleanrequired

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

    Loading...
    Last updated on