Skip to main content

Instance Transactions

An instance transaction represents an approval or rejection action on a sharing instance. When shared data requires explicit consent or verification — from the data provider or another party — the system creates a transaction that must be resolved before the instance can proceed.

How transactions work​

Transactions implement a challenge-response pattern:

  1. The system generates a unique challenge token for the transaction
  2. A notification is sent to the approver with the challenge details
  3. The approver responds — approving, rejecting, or the transaction fails due to a technical issue
  4. The system records the response along with geolocation data and any biometric verification

Transaction states​

Each transaction progresses through a defined set of states:

StateMeaning
PendingTransaction created, waiting for notification delivery
Notification sentThe notification has been delivered to the approver
ApprovedThe approver has accepted the transaction
RejectedThe approver has declined the transaction
FailedThe transaction could not be completed due to a technical failure

Biometric verification​

Transactions can optionally require biometric or passkey verification using WebAuthn. When this is enabled, the approver must authenticate with a registered credential (such as a fingerprint, face scan, or hardware security key) before the transaction can be resolved. This adds a strong assurance that the person approving the transaction is who they claim to be.

Background processing​

Transaction state changes trigger background jobs:

  • On creation — the system creates a job to deliver the notification to the approver
  • On state change — when the transaction is approved, rejected, or fails, a job is created to process the outcome and propagate any downstream effects

The notification-sent state is handled differently: it does not create a follow-up job, because it is set by the notification system itself. Creating another job at that point would cause an infinite loop.

Authorisation​

Transaction visibility follows the parent instance:

  • Data providers can see and manage transactions for their own sharing instances
  • Access application owners and editors can see and manage all transactions across all instances in their application

This means the receiving organisation can monitor and manage the approval workflow, while data providers can only interact with transactions related to their own submissions.