Skip to main content

Manage proof requests

Learn about the lifecycle of proof requests, including how proof states are reflected in the system and how to manage the claims data that wallet holders have shared with you.

Proof request states in the system​

To help you manage proof requests and interpret history logs, proof requests in the system have state representations to reflect where they are in the lifecycle.

Proof request states Proof request states for verifiers

Proof request deletion​

Before a wallet holder has responded to a proof request, the request can be deleted. If the request is in CREATED or PENDING state it is hard- deleted from the system and leaves no history behind. If the request is in REQUESTED state when deleted, it instead becomes RETRACTED and the history of the interaction is retained.

ISO mDL offline flow​

Proof requests made using the ISO mDL offline flow start in PENDING state. This is because the flow is initiated by the holder generating a QR code from their wallet. This QR code content is passed in the isoMdlEngagement parameter during proof request creation to establish the connection, bypassing the need for you to create QR code with the share endpoint.

ERROR state​

The ERROR state represents either the holder successfully submitting a presentation which could not be verified, such as when the credential has been revoked or the signature is invalid, or some error occurs during the presentation process, such as a timeout. An error message is returned to help you understand why it happened.

Holder rejection​

For most verification flows, the proof request states make no distinction between the holder rejecting a request and simply failing to respond. In both cases the proof request stays in its latest state: PENDING for HTTP verification and REQUESTED for BLE flows.

MQTT is an exception: when the holder rejects the request in the MQTT flow, the proof request state becomes REJECTED.

Credential states as a verifier​

When a proof is verified, any credentials presented as part of that proof enter the system and exist in one state: ACCEPTED.

Credentials states - verifier Credential states for verifiers

Verification is a point-in-time event with a binary result: the holder's presentation is either verified or it's not. While there are a number of reasons a presentation may fail, there is only one reason a presentation will be verified: the holder submitted a valid proof.

The system does not monitor or update the credential's status over time in any way because the interaction is completed.

You can implement custom business logic to act on specific claims within the credential. For example, if the credential includes an expiration date claim, your application can use that information to trigger appropriate business processes. The system simply stores this as a regular claim, leaving the interpretation and handling of such time-sensitive data to your application logic.

Delete claim data​

There are two ways to delete claim data wallet holders share with you:

  • Set a claim data expiration when creating the proof schema. For all proof requests made using a given proof schema, the system automatically deletes claim data when it reaches expiration.

    info

    The task RETAIN_PROOF_CHECK checks received claims against their expireDuration and deletes them once it has passed. When you build your application, decide how often and when you want to run this check.

  • Manually delete claim data when you no longer need it. Use the DELETE method on the /api/proof-request/v1/:id/claims endpoint.

In both cases, the system deletes the claim values and credential information such as issuer and holder identifiers. The system retains proof request metadata such as what was requested, when the transaction occurred, and when the claim data was deleted.