Skip to main content

Update presentation definition

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

Updates a presentation definition.

The update endpoint reads fewer properties than the create endpoint. It reads label, dcqlQuery, transactionDataDefinitionType, clientIdScheme, directPostRedirectUri, responseMode, dcApiRequestType and expectedOrigins. It ignores version, trustAnchor, kid, scope, responseType and encryptedResponseEncValuesSupported. To change one of the ignored properties, delete the presentation definition and create it again.

The server keeps the current label when you send no label, a label of one character, or a label of only spaces. Unlike create, update does not apply a 3-character minimum, so a 2-character label is accepted and stored.

Rules that the server applies:

  • label must not be a label that an extension reserves, for example 'Age Verification', 'Document Signing' or 'Know-Your-Customer (KYC)'.
  • 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.
  • directPostRedirectUri is allowed only when the effective responseMode is direct_post. The server refuses it for direct_post.jwt.
  • dcApiRequestType is allowed only when 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.

This endpoint cannot set clientIdScheme to null. Send no clientIdScheme to make the server use redirect_uri.

Request​

Path Parameters

    presentationDefinitionId stringrequired

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

Header Parameters

    X-SandboxOrgId stringrequired

    Optional. Unique identifier of the sandbox organisation to use for this request. When you send this header, the service runs the operation in the context of the named sandbox organisation, that is, against the wallet of that sandbox organisation and not against the main wallet of the organisation. Leave the header out to use the main wallet.

    The service reads this header only when you authenticate with a bearer access token. When you authenticate with an API key, the service takes the sandbox organisation from the API key and ignores this header. To run an API-key call in a sandbox organisation, bind the key to the sandbox organisation with PUT /v2/config/admin/apikey/{apiKeyId}/sandbox-org instead.

    X-SubwalletId is the deprecated name of this header. The service continues to accept it, but X-SandboxOrgId wins if you send both headers.

    The sandbox organisation must exist, must belong to your organisation and must be deployed. An unknown identifier, an identifier of a sandbox organisation that is not deployed, and an identifier that belongs to a different organisation all make the call fail with HTTP 400.

    Example: 6889e1a4c5b2f30001a3d710

Body

required

Properties of the presentation definition to change. The server ignores every other property.

    label string

    Possible values: non-empty and <= 100 characters

    New human-readable label of the presentation definition. Update does not apply the 3-character minimum of the create endpoint, so a 2-character label is accepted and stored. The server keeps the stored label when you send a label of one character, or a label of only spaces. 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 and a format. The format controls which meta keys the server accepts: mso_mdoc takes doctype_value only, dc+sd-jwt takes vct_values or type_values, and jwt_vc_json takes type_values only. The vc+sd-jwt, vp+sd-jwt and jwt_vc formats take no meta key at all. 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 and a format. The format controls which meta keys the server accepts: mso_mdoc takes doctype_value only, dc+sd-jwt takes vct_values or type_values, and jwt_vc_json takes type_values only. The vc+sd-jwt, vp+sd-jwt and jwt_vc formats take no meta key at all. 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.

    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.

    clientIdScheme string

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

    New client ID scheme of the Authorization Request. The scheme sets how the verifier identifies itself to the wallet of the holder. The server uses redirect_uri when you send no value.

    directPostRedirectUri string

    New URI that the wallet opens after it posts the Authorization Response. Only for the direct_post response mode. The server refuses this property for direct_post.jwt.

    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 in production.

    expectedOrigins string[]

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

    property name* any

Responses​

The server updated the presentation definition.

Response Headers
    Schema
      presentationDefinition objectrequired
      id stringrequired

      Internal record identifier of the presentation definition. The list endpoint returns the value of presentationDefinitionId here. The create, read and update endpoints return a different internal identifier. Always use presentationDefinitionId to address the presentation definition.

      openIdOrganisationId stringrequired

      Identifier of the OpenID4VC deployment 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 or type_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 or type_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.

      kid stringrequired

      Key Identifier (kid) of the cryptographic key that the verifier uses to sign the Authorization Request and to receive an encrypted response. The value is an empty string when the presentation definition holds no key identifier.

      trustAnchor string

      Possible values: [did:key, x509]

      DID method or key type that the verifier uses as its trust anchor. It sets how the holder resolves the identity of the verifier.

      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, id_token, device_response]

      OAuth 2.0 response type of the Authorization Request. vp_token asks for a Verifiable Presentation. id_token asks for an OpenID Connect ID Token. 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. Only for the direct_post response mode. The server refuses this property for direct_post.jwt, and it has no meaning for the DC API 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. The verification request then falls back to all three algorithms.

      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 object

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

      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. You cannot set this property.

    Loading...
    Last updated on