For the complete documentation index, see llms.txt. This page is also available as Markdown.

Verifiable Presentation

Get presentation states

get

Get presentation states.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
walletIdstringRequired
Query parameters
orderstring · enumOptional

Presentation States response order. Default ordering: DESC (Supported: ASC, DESC)

Example: DESCPossible values:
order_bystring · enumOptional

Order Presentation States by an attribute, defaults to: created_at (Supported: created_at)

Example: created_atPossible values:
per_pageinteger · min: 1 · max: 50Optional

Number of records per page

Example: 10
pageinteger · min: 1Optional

Page number (starting from 1)

Example: 1
Responses
200

Presentation states successfully loaded

application/json
get/wallets/{walletId}/send

Register authorization request

post

Parse the authorization request URI and get the following information.

  • client_id: The Client ID of the verifier.

  • client_metadata: Verifier client metadata.

  • nonce: Nonce provided by the verifier to be returned in the response

  • presentation_definition: What credentials the verifier is requesting from the Wallet in PEX format.

  • dcql_query: What credentials the verifier is requesting from the wallet in DCQL format.

  • redirect_uri: The redirect URI of the verifier.

  • response_mode: How to return the response.

  • response_type: Which parameters to use to return the presentation to the verifier.

  • response_uri: Where to send the response.

  • verifier_state: State passed by the verifier to link request and response.

  • meta.protocol_version: Version of the protocol to be used. Supported values: openid4vp-v1. The default value is openid4vp-v1.

This information informs the Wallet how to process the request and respond to the verifier.

Request Parameters

The following sections describe in more detail the parameters, their default values and behaviour.

client_id (required)

Client ID is a parameter identifying the Relying Party (RP) - the entity requesting and consuming a Verifiable Presentation. It is used by the Holder's Wallet to fetch and validate client metadata, and to establish trust before releasing Verifiable Presentations.

Client ID consists of two parts:

  • prefix - to define the type of the identifier

  • identifer - identifier value

Supported prefixes are: redirect_uri, decentralized_identifier and x509_san_dns.

client_metadata (required)

Client metadata, also called verifier metadata in this case can be implemented using static configuration values, as well as employ Dynamic Discovery.

The static configuration is usually bound to an existing profile, for example.

They use specific, custom URL schemes such as openid-vc or haip. When these are used, values referred to in these profiles should be used as client metadata.

Each network can define their own set of static configuration values for client metadata.

The use of fedarations or trust schemes is not yet supported.

Component does not support authorization_signed_response_alg configuration. If one is provided together with response_mode = direct_post.jwt - Presentation Request will not be parsed and registered.

nonce

Nonce to be returned in the response to prevent replay attacks.

presentation_definition (required)

Expresses which credentials a verifier asks a wallet to present. The syntax to do this should conform to DIF Presentation Exchange specification. The structure of the definition is validated by a JSON schema associated with the presentation_definition schema in the OpenAPI definition.

It is also possible to use presentation_definition_uri. In this case the wallet performs a GET request to the presentation_definition_uri and parses the response. The response is stored in the presentation_definition attribute.

Note that the service does not necessarily support all options defined in the Presentation Exchange specification.

API expects presentation_definition.input_descriptors[].format to be defined. If it is missing, authorization request is not going to be registered.

response_mode

How the response is sent to the verifier. Possible values are

  • direct_post: In this mode, the Authorization Response is sent to the Verifier using an HTTPS POST request to an endpoint controlled by the Verifier. The Authorization Response parameters are encoded in the body using the application/x-www-form-urlencoded content type.

  • direct_post.jwt: In this mode, the Authorization Response is sent to the Verifier using an HTTPS POST request to an endpoint controlled by the Verifier. The Authorization Response is encoded as a JWE (JSON Web Encryption) and included in the body of the request, allowing for confidentiality and integrity protection. Unlike direct_post, this mode ensures that the entire Authorization Response is encrypted when transmitted to the Verifier.

When using direct_post or direct_post.jwt, note that the redirect_uri must be returned after successfully posting the Authorization Response to the response_uri.

Note that fragment is currently not supported.

response_uri

If the response_mode is direct_post this is the URI to send the response to.

verifier_state

Opaque state that can be used to link the request and response. Is returned as the state parameter in the Authorization Response.

Use of JAR (RFC9101)

JAR (RFC9101) is a JWT representation of the request. The JWT is signed with the verifier's private key. There are two ways to do this.

  • request: The request parameter is the JWT representation of the request.

  • request_uri: The request_uri parameter is the URL of the request.

In most cases request_uri is used instead of request as it is more convenient, especially in situations when a QR code is used to represent the authorization request.

The JAR contains the necessary information and is fetched, verified and subsequently parsed. See the previous section for more details.

Examples

Below are some examples of valid authorization requests and how they are parsed.

This is an example where JAR is used. First, the request_uri is used to fetch the request JWT. The JWT is validated and then parsed. The parsed request is stored in the metadata.request attribute. All the required information, except for the client_id is fetched from the JWT, validated and stored.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
walletIdstringRequired
Body
authorization_request_uristringRequiredExample: openid-vc://?request_uri=https://example.com/oidc/presentations/requests/c63aa3e9-dc7d-4753-9ac8-30bf7add6e4c/jwt
protocol_versionstring · enumOptional

Specification draft version presentation request uses. If not specified openid4vp-v1 is used.

Possible values:
Responses
201

Successful registration of the presentation authorization request.

application/json
authorization_request_uristringOptionalExample: openid-vc://?request_uri=https://example.com/oidc/presentations/requests/c63aa3e9-dc7d-4753-9ac8-30bf7add6e4c/jwt
client_idstringOptional
noncestringOptional

Nonce provided by the verifier to be returned in the response

redirect_uristringOptional
response_modestring · enumOptional

Parameter to ask the Wallet to send the response to the verifier. Possible values are 'direct_post'

Possible values:
response_typestring · enumOptional

Response type of the request. Possible values are vp_token, id_token

Possible values:
response_uristringOptional

Response uri of the request. Only relevant if response type is direct_post

statestringOptionalExample: e0d7bd1e-dce5-4366-989f-4647af68412a
verifier_statestringOptional

State provided by the verifier to be returned in the response

post/wallets/{walletId}/send

Set the credentials to be presented

post

Set the credentials to be presented as part of this presentation response.

Each credential must be linked to an input descriptor from the credential definition. There is one important condition to present mso_mdoc credentials. mso_mdoc credential doctype attribute value must match input_descriptors[].id othwerwise submitting a presentation will fail. There are no such conditions for jwt_vc_json and dc+sd-jwt credential formats. For credentials that support selective disclosure (dc+sd-jwt, mso_mdoc), there is the possibility to use the claims_to_disclose property. Use object notation to specify which claims to disclose. For example:

"claims_to_disclose": ["given_name", "address.street_address", "address.locality", "nationalities[0]"]
"claims_to_disclose": ["$['org.iso.18013.5.1']['birth_date']", "$['org.iso.18013.5.1']['given_name']"]

If a claim or a nested claim is not found in the credential or it doesn't support selective disclosure, it will be ignored.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
walletIdstringRequired
Body
statestringRequired
Responses
201

Successful registration of the credential offer.

application/json
statestringRequired
post/wallets/{walletId}/send/set_credentials

Submit the presentation response to the verifier

post

Generate the presentation response to present the credentials to the verifier.

Based on the response_type, the following parameters are included in the response:

The response always includes:

  • vp_token: A single JSON string or array of JSON strings representing the presentation.

  • presentation_submission: A JSON object containing the mapping between the requested credentials and where to find them in the returned VP token. This follows the DIF Presentation Exchange specification.

Optionally, the following is also included:

  • id_token: A single JSON string that proves control of the wallet over key material.

Depending on the response_mode option, the response can be sent to the verifier using an HTTPS POST request or an HTTP redirect.

In case of response_mode=fragment (default), the response is sent via the front channel by opening the redirect_uri, which is returned in the response to this request. This redirect_uri includes all the response parameters. Note that this is currently not supported.

In case of response_mode=direct_post or response_mode=post, the response is submitted via an HTTPS POST request to the response_uri. In this case, it is expected that a redirect_uri is returned in the response to this request. This redirect_uri is also to be opened in the front channel, but is simply used to continue the verification process and not to transmit the response to the verifier.

In case of response_mode=direct_post.jwt, the response is submitted via an HTTPS POST request to the response_uri as a JWE. In this case, it is expected that a redirect_uri is returned in the response to this request. This redirect_uri is also to be opened in the front channel, but is simply used to continue the verification process and not to transmit the response to the verifier.

The status of this submission can be tracked via the meta.submission_status attribute. Note that in case of response_mode=fragment, the status is always success.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
walletIdstringRequired
Body
client_idstringOptional
noncestringOptional

Nonce provided by the verifier to be returned in the response

redirect_uristringOptional
response_modestring · enumOptional

Parameter to ask the Wallet to send the response to the verifier. Possible values are 'direct_post', 'post'.

Possible values:
response_typestring · enumOptional

Response type of the request. Possible values are vp_token, id_token

Possible values:
response_uristringOptional

Response uri of the request. Only relevant if response type is direct_post

statestringRequired
verifier_statestringOptional

State provided by the verifier to be returned in the response

Responses
201

Successful submission of presentation response

application/json
redirect_uristringOptional

Redirect URI to follow on the frontend.

In case of response_mode fragment, this contains the Authorization Response attributes and this is how they are passed to the verifier.

In case of response_mode direct_post, this is the URI that was returned after successfully posting the Authorization Response to the response_uri of the verifier.

statestringOptional
post/wallets/{walletId}/send/submit

Get present credential state

get

Get present credential state.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
walletIdstringRequired
statestringRequired
Responses
200

Successful registration of the credential offer.

application/json
authorization_request_uristringOptionalExample: openid-vc://?request_uri=https://example.com/oidc/presentations/requests/c63aa3e9-dc7d-4753-9ac8-30bf7add6e4c/jwt
client_idstringOptional
noncestringOptional

Nonce provided by the verifier to be returned in the response

redirect_uristringOptional
response_modestring · enumOptional

Parameter to ask the Wallet to send the response to the verifier. Possible values are 'direct_post'

Possible values:
response_typestring · enumOptional

Response type of the request. Possible values are vp_token, id_token

Possible values:
response_uristringOptional

Response uri of the request. Only relevant if response type is direct_post

statestringOptionalExample: e0d7bd1e-dce5-4366-989f-4647af68412a
verifier_statestringOptional

State provided by the verifier to be returned in the response

get/wallets/{walletId}/send/{state}

Delete Verifiable Presentation State by ID

delete

Delete state of a presentation flow

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
walletIdstringRequired
statestringRequired
Responses
204

Presentation State by ID successfuly removed

No content

delete/wallets/{walletId}/send/{state}

No content

Last updated