Built by the community
Navigation
Metrics
Program
Service DeskPricingPoliciesDocument RepositoryLive Ecosystem
Developer Docs
TPP — Open Finance StandardsLFI — Integration GuideAPI SpecsKnowledge BaseRelease Notes & Erratas
NewsGitHub
Validate · Enforce · Trust

Insurance Data Sharing — Requirements v2.110 min read

The Authentication requirements, Authorization requirements, and User Journeys must be adhered to.

The tables below list the rules that apply to Insurance Data Sharing. All request validation of the TPP's credentials, access token, and consent is performed by the Hub before your Ozone Connect endpoints are called. The rules below cover what your Ozone Connect endpoints must validate and what they must return. The cross-cutting Policy Access Validation check applies to GET /{type}-insurance-policies/{InsurancePolicyId}. Insurance has a five-year data retention floor — your Ozone Connect endpoints MUST return policies from the last five years regardless of current PolicyStatus; there is no status-based 403.

01 Section

Consent Validation

When a TPP creates an insurance consent, the API Hub calls your POST /consent/action/validate endpoint before the consent is created. You MUST validate the consent and respond with status: "valid" or status: "invalid". If you respond with invalid, the API Hub will not create the consent and the TPP will receive an error. This validation runs before the customer is involved — there is no authentication or authorization at this stage. The purpose is to reject consents early that your systems cannot fulfil. The field names in the rules below match the Ozone Connect newConsent payload the Hub delivers — consentType is cbuae-insurance-consents, standardVersion sits at the top level of the consent object, and Permissions sits under consentBody.Data as an array of { InsuranceType, Permissions[] } blocks.

#
Rule
Detail
1
Unsupported standardVersion
The consent's standardVersion (a top-level property on the consent object) is the URL path version the TPP will call on subsequent insurance requests. If you do not support that version for the Insurance API family, respond with invalid.

Where you are dual-running multiple versions during a deprecation window (see Major Version Deprecation) — for example v2.0 alongside v3.1 — you MUST respond valid for every version you serve.

Minor versions are backward compatible (see Version Management), so prior minors within each major you run are also valid (e.g. running v2.0 and v3.1 means v2.0, v3.0, and v3.1 all resolve to valid).
2
Unsupported InsuranceType
If any per-sector block in consent.Permissions references an InsuranceType the LFI does not underwrite (e.g. the LFI does not offer Renters products but the consent requests Renters), respond with invalid. Validate against the sectors you have onboarded with Nebras.
3
Unsupported permissions
If a per-sector block requests a permission the LFI does not surface for that sector (e.g. the consent includes ReadCustomerClaims for Motor but the LFI does not yet expose claims for Motor policies), respond with invalid.
4
ReadInsurancePolicies required per sector
Every per-sector block MUST contain ReadInsurancePolicies — it is the base permission that gates list and detail access. If a block omits it, respond with invalid.
5
Invalid BaseConsentId
If the consent includes a BaseConsentId, validate that:
  • The BaseConsentId references an existing consent known to the LFI.
  • The referenced consent is an Insurance Data Sharing consent (authorization_details[0].type is urn:openfinanceuae:insurance-consent:*).
  • The referenced consent does not itself have a BaseConsentId — if it does, the TPP has incorrectly linked to an intermediate consent in the chain rather than the root consent. The BaseConsentId must always reference the original root consent.
If any of these checks fail, respond with invalid.
02 Section

Authorization — Policy Selection

The generic Authorization requirements apply to this journey. The rules below cover the additional policy selection logic specific to Insurance Data Sharing. During the consent authorization journey, the customer selects which of their policies to share with the TPP, scoped to the sectors the consent grants.

#
Field
Rule
1
consent.Permissions[*].InsuranceType
Only present policies of sectors listed in consent.Permissions. A consent that grants Motor and Home only surfaces policies in those two sectors — Travel and Health policies the customer may also hold MUST NOT appear.
2
Five-year selection window
Within each consented sector, present every policy the customer holds or has held in the last five years, regardless of current PolicyStatus. Historical policies (Expired, Lapsed, Cancelled, Surrendered, etc.) MUST be selectable so the customer can share historical insurance history for switching, broking, and advisory use cases. Each row MUST clearly label the policy's current PolicyStatus so the customer is not misled into thinking a lapsed policy is still active.
3
No eligible policies
If the authenticated customer does not hold any policies within the five-year window across any of the consented sectors, PATCH the consent to Rejected and call doFail with error: invalid_request and error_description: user_lacks_eligible_policies. See Authorization requirements for details.
4
Multiple selection
The policy selection screen must allow the customer to select more than one policy and to select policies across different sectors in a single consent. A consent with no policies selected must not be authorised.
5
insurancePolicyIds patch
On successful authorization, PATCH the consent with insurancePolicyIds set to the array of InsurancePolicyId values the customer selected. This array is the authoritative consented set used by every subsequent data sharing request — see Policy Access Validation.
03 Endpoint

List Policies (per sector)

GET/{type}-insurance-policies

The Hub calls this endpoint with the sector slug (employment, health, home, life, motor, renters, or travel) baked into the path and passes InsurancePolicyIds as a query parameter listing the IDs the consent authorised for that sector.

#
Field
Rule
1
InsurancePolicyIds
Return the policies whose InsurancePolicyId matches one of the values in the InsurancePolicyIds query parameter and whose sector matches the URL path. Populate the PolicyStatus field on each policy so the TPP can see the current state.
2
Five-year retention
Return every consented policy from the last five years regardless of current PolicyStatus. This is a minimum availability floor, not a query limit — the endpoint MAY return policies older than five years where it holds them. A PolicyStatus of Expired, Lapsed, Cancelled, Surrendered, etc. MUST NOT cause the policy to be omitted from the response within the retention window.
3
Data completeness
All fields that exist or are derivable from your systems must be populated on each policy. All fields marked as required in the OpenAPI spec must be present, including InsurancePolicyId, PolicyNumber, PolicyStatus, Insurer, and the sector-specific identifiers.
4
Premium
If the consent for this sector includes ReadInsurancePremium, populate the Premium field on each policy in either the cleartext or JWE shape per Premium Encryption. If the consent does not include ReadInsurancePremium, omit the Premium field entirely — do not return an empty object or a placeholder.
5
Permission-scoped fields
Populate optional field sets only when the matching permission is granted in the per-sector block: ReadCustomerBasic / ReadCustomerDetail for policy-holder identity; ReadCustomerPaymentDetails for payment methods; ReadInsuranceProduct for underwritten product detail; ReadCustomerClaims for claims history. Fields the consent does not unlock MUST be omitted.
6
No pagination
Return every matching policy in a single response. There is no page query parameter on the TPP-facing API, and Meta MUST NOT include TotalPages or TotalRecords. The full consented set for the sector MUST fit in one payload.
7
Empty result
If the customer holds no policies in the sector within the five-year window, return 200 with an empty Policy array. Do not return 404.
8
Policy access
For every InsurancePolicyId in the InsurancePolicyIds query parameter, validate that the policy is held — or was held within the five-year window — by the customer resolved from o3-psu-identifier. If any requested policy is not held by the customer, return 403 per Policy Access Validation.
04 Endpoint

Get a Policy

GET/{type}-insurance-policies/{InsurancePolicyId}
#
Field
Rule
1
policy
Return the single policy whose InsurancePolicyId matches the value in the path parameter and whose sector matches the URL path.
2
Five-year retention
Return the policy regardless of current PolicyStatus, provided its end date (or last activity date) is within the last five years. There is no status-based 403 on this endpoint — the policy is the artifact, and the customer has consented to share it.
3
Data completeness
All fields that exist or are derivable from your systems must be populated, consistent with what is returned by the list endpoint for the same policy. All fields marked as required in the OpenAPI spec must be present.
4
Premium
If the consent includes ReadInsurancePremium, populate Premium in either the cleartext or JWE shape per Premium Encryption. Otherwise omit the field.
5
Permission-scoped fields
Populate optional field sets only when the matching permission is granted in the per-sector block. Fields the consent does not unlock MUST be omitted from the detail response, the same way as on the list response.
6
Policy access
Validate that the InsurancePolicyId in the path parameter is part of the consented set held by the customer resolved from o3-psu-identifier. Apply the Policy Access Validation check before returning — an ID outside the consented set MUST return 403 with errorCode: Consent.PermanentPolicyAccessFailure.
05 Section

Premium Encryption

The Premium field on every insurance policy response is defined as anyOf a structured AEInsurance.AEInsuranceDataSharingPremiumProperties object or an AEInsurance.AEInsurancePremiumJWE compact string. Your LFI decides, per policy, which shape to return. The rules below cover both shapes. See the producer-side walkthrough for end-to-end detail.

#
Field
Rule
1
Permission gating
Only populate Premium when the per-sector block in consent.Permissions includes ReadInsurancePremium. If the permission is absent, omit the field entirely.
2
Premium format
Premium may be returned as either a cleartext AEInsurance.AEInsuranceDataSharingPremiumProperties JSON object or as a JWE compact serialisation string. Encryption is at the LFI's discretion per policy.
3
Premium — JWE
If encrypting Premium, generate an ephemeral symmetric encryption key per response (must not be reused). Encrypt the structured premium payload as a JWE using the content encryption algorithm required by the Security Profile. Set exp to 30 minutes from the time of the response and set kid to the value of x-fapi-interaction-id. Transmit the encryption key to the User via an existing LFI channel (e.g. SMS or push notification) — do not include it in the API response.
4
Shape exclusivity
A single policy response carries exactly one of the two shapes — either the cleartext object or the JWE string. Do not include both, do not embed the JWE inside the structured object, and do not return a partially populated structured object alongside a JWE.
06 Section

Policy Access Validation

Every endpoint that takes a policy identifier — whether as the InsurancePolicyId path parameter on GET /{type}-insurance-policies/{InsurancePolicyId} or as values in the InsurancePolicyIds query parameter on GET /{type}-insurance-policies — MUST validate that each policy is part of the consented set held by the customer resolved from the o3-psu-identifier header before applying the per-endpoint rules above. Policy ownership is authoritative on the LFI side — the Hub stores the insurancePolicyIds patched onto the consent at authorization, but the LFI is the source of truth for which policies the customer actually holds or has held.

If any requested policy is not part of the consented set, return 403 with errorCode: Consent.PermanentPolicyAccessFailure and errorMessage: The policy is permanently inaccessible. This check applies uniformly regardless of PolicyStatus — a policy that is Lapsed or Expired is still readable provided it is in the consented set; a policy that is Active but outside the consented set MUST NOT be returned.