Draft

This is v2.2-draft — a working draft of the v2.2 standards, published for review and not yet ratified. It MUST NOT be used as the basis for a production implementation. For the current standards, switch to v2.1 using the version selector. See the v2.1 → v2.2-draft changelog for every change in this version.

Validate · Enforce · Trust

Insurance Data Sharing — Requirements v2.2-draft10 min read

The validation rules that apply to Insurance Data Sharing. The Validated by column on each table indicates where each rule is enforced. Read alongside the Consent requirements and the User Journeys.

All requests require an active Trust Framework application with the ISP role, a valid transport certificate presented on every request via mTLS, an active signing key for JWT signing, and — when requesting ReadInsurancePremium — an active encryption key for decrypting the Premium JWE on the customer device.

01 Endpoint

Consent Creation

POST/par

Field

Rule

Validated by

Request JWT

Must conform to the Request JWT requirements — correct aud, signing algorithm (PS256), and expiry window.

API Hub

client_assertion

Must be included in the POST body (client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer). Authenticates the TPP application — see Client Assertion.

API Hub

scope (in Request JWT)

Must be openid insurance.

API Hub

authorization_details[0].type (in Request JWT)

Must be urn:openfinanceuae:insurance-consent:v2.2.

API Hub

API version supported

The consent version in authorization_details[0].type (e.g. urn:openfinanceuae:insurance-consent:v2.2) restricts the version of the Insurance endpoints the consent can be used to call (specified in the path, e.g. /open-finance/insurance/v2.2/motor-insurance-policies). It MUST resolve to an ApiVersion the LFI has published in the Trust Framework for the Insurance API family.

LFI/consent/action/validate

OpenAPI schema

The request must conform exactly to the POST /par OpenAPI schema. No additional or undocumented parameters are permitted.

API Hub

consent.Permissions structure

Must be a non-empty array. Each entry is a per-sector block of the form { InsuranceType, Permissions[] }. There MUST be at least one block, and each block MUST contain at least one permission code.

API Hub

consent.Permissions[*].InsuranceType

Each value must be one of: Employment, Health, Home, Life, Motor, Renters, Travel. Each sector may appear at most once in the array. The sector must also be one the LFI underwrites — if the LFI does not offer the requested sector, the validate hook will reject the consent.

LFI/consent/action/validate

consent.Permissions[*].Permissions

Within each per-sector block, ReadInsurancePolicies MUST be present — it is the base permission that gates list and detail access for the sector. Other permissions (ReadCustomerBasic, ReadCustomerDetail, ReadCustomerPaymentDetails, ReadInsuranceProduct, ReadCustomerClaims, ReadInsurancePremium) MAY be included and unlock the corresponding field sets on the policy response.

API Hub

consent.Permissions[*].Permissions — ReadInsurancePremium

ReadInsurancePremium MUST only be requested by TPPs that hold the Access Encrypted Resource Data optional certification with Nebras. An uncertified TPP MUST NOT include this permission in any per-sector block; if it does, the API Hub rejects the consent. Only certified TPPs are permitted to receive insurance premium data, whether the LFI returns it in cleartext or as an encrypted JWE.

API Hub

consent.Permissions (unsupported)

If a per-sector block requests a permission the LFI does not expose for that sector (e.g. ReadCustomerClaims for a sector the LFI does not surface claims on), the consent validation will fail.

LFI/consent/action/validate

consent.BaseConsentId

If provided, must reference a previous consent belonging to the same end user and must be an Insurance Data Sharing consent (authorization_details[0].type is urn:openfinanceuae:insurance-consent:*). If the original consent in the chain already had a BaseConsentId, the TPP must reuse that same BaseConsentId rather than the immediate prior ConsentId.

LFI/consent/action/validate

consent.ExpirationDateTime

Must not be in the past. Must be less than one year in the future.

API Hub

x-fapi-interaction-id

Should be included. Should be a valid UUID (RFC 4122). An invalid value will not cause a failure but tracing will not be possible.

N/A

02 Section

Authorization — Policy Selection

Field

Rule

Validated by

Eligible policies

If the authenticated customer does not hold any policies in any of the consented InsuranceType sectors, the consent will be set to Rejected with error: invalid_request and error_description: user_lacks_eligible_policies.

LFI

Selection breadth

The selection screen must allow the customer to choose any subset of policies surfaced. A consent with no policies selected must not be authorised.

LFI

03 Endpoint

List Policies

GET/{type}-insurance-policies

Field

Rule

Validated by

Authorization

Must contain a valid Bearer access token issued with the openid insurance scope. The consent bound to the token must be in Authorized status and the ExpirationDateTime of the Consent must be in the future.

API Hub

URL version

The version in the request URL path (e.g. v2.2 in /open-finance/insurance/v2.2/motor-insurance-policies) must match the version in the consent’s authorization_details[0].type (urn:openfinanceuae:insurance-consent:v2.2).

API Hub

{type} path segment

Must match an InsuranceType present in consent.Permissions. A call to a sector the consent does not grant returns 403.

API Hub

consent.Permissions

The per-sector block for the requested InsuranceType must include ReadInsurancePolicies.

API Hub

Pagination

Not applicable. The endpoint returns the full set of consented policies for the sector in a single response — there is no page query parameter, and Meta does not include TotalPages or TotalRecords.

N/A

Historical policies

The response includes every policy the customer authorised within the last five years, regardless of current PolicyStatus. TPPs MUST be prepared to receive policies in any of the AEInsurancePolicyStatusCodes states (New, Renewed, Expired, Lapsed, Cancelled, PaidUp, Converted, Surrendered, DeathClaim, RiderClaim) and render them with their current status.

LFI

x-fapi-interaction-id

Should be included. Should be a valid UUID (RFC 4122). An invalid value will not cause a failure but tracing will not be possible.

N/A

x-fapi-auth-date

Must be sent when the customer is authenticated at the time of the call. Must be a valid HTTP-date (RFC 7231), e.g. Tue, 11 Sep 2012 19:43:31 UTC.

TPP

x-fapi-customer-ip-address

Must be sent when the customer is actively present at the time of the call. Must be a valid IPv4 or IPv6 address.

TPP

x-customer-user-agent

Should be sent when the customer is actively present. Should reflect the user-agent of the customer’s browser or device.

TPP

04 Endpoint

Get a Policy

GET/{type}-insurance-policies/{InsurancePolicyId}

Field

Rule

Validated by

Authorization

Must contain a valid Bearer access token bound to an Authorized consent that has not expired.

API Hub

URL version

The version in the request URL path must match the version in the consent’s authorization_details[0].type.

API Hub

{type} path segment

Must match an InsuranceType present in consent.Permissions.

API Hub

consent.Permissions

The per-sector block for the requested InsuranceType must include ReadInsurancePolicies. The field sets returned on the policy depend on the additional permissions in the block (ReadCustomerBasic, ReadCustomerDetail, ReadCustomerPaymentDetails, ReadInsuranceProduct, ReadCustomerClaims, ReadInsurancePremium).

API Hub

InsurancePolicyId

Must be a valid policy ID shared by the customer — i.e. returned by GET /{type}-insurance-policies under the same consent. See Policy Access Validation for the response when the policy is not part of the consented set.

LFI

Historical policies

The endpoint returns the policy regardless of current PolicyStatus within the five-year window — there is no status-based 403. TPPs MUST render the policy according to its PolicyStatus rather than assume it is active.

LFI

x-fapi-interaction-id

Should be a valid UUID (RFC 4122).

N/A

x-fapi-auth-date

Must be sent when the customer is authenticated at the time of the call.

TPP

x-fapi-customer-ip-address

Must be sent when the customer is actively present at the time of the call.

TPP

x-customer-user-agent

Should be sent when the customer is actively present.

TPP

05 Section

Premium Handling

Field

Rule

Validated by

Premium — key request

If Premium is returned as a JWE, the TPP must prompt the User to enter the encryption key delivered to them by the LFI (e.g. via SMS or push notification) before decryption can proceed.

TPP

Premium — local decryption

Decryption of the JWE must be performed locally on the User’s device. The decrypted data must not be transmitted to the TPP’s servers or persisted in any storage accessible to the TPP’s application.

TPP

Premium — data usage

The decrypted data must only be used to display the premium to the User within the active session. The TPP must not store, transmit, or otherwise process the unencrypted data.

TPP

Premium — expiry

The TPP must observe the exp value in the JWE header and discard any decrypted data once the expiry threshold has passed. If the data is still required, the TPP must repeat the API operation to retrieve a fresh response — the original consent must still be valid for this to succeed.

TPP

Premium — session discard

The TPP must discard all decrypted data from memory when the User closes their session, regardless of whether exp has been reached.

TPP

06 Section

Policy Access Validation

Scenario

Response

InsurancePolicyId is not part of the consented set for the sector

403 with errorCode: Consent.PermanentPolicyAccessFailure and errorMessage: The policy is permanently inaccessible.