Skip to main content

Instances and Instance Nodes

When a user shares their data through an access application, the system creates an instance to represent that sharing event. Each instance contains instance nodes — copies of the specific data nodes that were shared.

What is an instance?​

An instance represents a single occurrence of data sharing. It is to an access application what a form submission is to a form definition. Each instance tracks:

  • Which access application it belongs to, and which encryption key was used
  • The data provider's identity — their email, the device they used, and their IP address
  • A confirmation code — an auto-generated six-digit code that can be used to reference the submission
  • A score — the result of applying the application's ruleset to the submitted data
  • The current state — where the instance is in its lifecycle

Instance lifecycle​

An instance progresses through a series of states:

Each state transition triggers background processing:

  • Submitted — the system processes the submission event, which may trigger notifications to the receiving organisation
  • Pending — the system processes the instance asynchronously, applying rules and updating scores

The Started state is the initial state set on creation and does not trigger any processing.

Bot protection​

If the parent access application has bot protection enabled (such as Cloudflare Turnstile), the system validates the challenge token before allowing an instance to be created. This prevents automated or fraudulent submissions.

Viewing instances​

The DSM provides separate views for data providers and data receivers:

  • Data provider view — shows only instances that the current user created (their own submissions), including details about which organisation received the data
  • Data receiver view — shows only instances that other users created (submissions received by the organisation)

This separation makes it straightforward for the client application to distinguish between "data I have shared" and "data others have shared with me".

What are instance nodes?​

An instance node links a sharing instance to a specific profile node. It records which nodes were shared, which fields were included, and provides a snapshot of the node's data at the time of sharing.

Privacy through hashing​

When nodes are shared, the system generates a hashed version of the node identifier. Data receivers see this hashed reference rather than the original node ID. This privacy-preserving design means receivers can reference and work with shared data without being able to trace it back to the provider's internal data structure.

Node owners retain access to both the hashed and original identifiers, so they can always see exactly which of their nodes have been shared and where.

Field-level encryption​

Each instance node can have field-level encryption keys — separate keys for individual fields within the shared data. This enables selective decryption: a receiver may have the keys to decrypt some fields but not others, supporting fine-grained access control over shared information.

Instance node relationships​

When nodes have relationships in a user's profile (for example, a passport node linked to a person node), those relationships are preserved in the shared context. Instance node relationships mirror the original node relationships but use hashed identifiers, maintaining the privacy model within the shared data.

On-sharing​

The DSM supports on-sharing — where data received through one instance is re-shared to another access application. This creates a chain of custody that tracks how data flows between organisations. Each on-sharing link records the source instance, the destination instance, and the destination application.

Instance application objects​

In addition to shared profile nodes, an instance can contain application objects — data generated by the application logic itself rather than data shared by the user. Examples include computed results, compliance assessments, or risk scores produced during the sharing workflow.

Authorisation​

Instance nodes inherit access from their parent entities through structural authorisation tuples:

  • Access application editors can see all instance nodes across all instances
  • Instance viewers can see the nodes within their instance
  • Node owners can see where their nodes have been shared