1. API Flows

1.1 Step 1: Agree Insurance Consent for Data Sharing

The flow MUST begin with a User providing consent to the TPP for undertaking Insurance Quote and Data Sharing operations.

The consent required is based on the operations that are permitted:

• For Insurance Quotes without Data Sharing consent must be agreed between the User and TPP. The TPP can solicit quotes from LFIs without sharing data as part of the quote operation.

• For Data Sharing, with or without Quotes, consent is agreed between the User and TPP before consent is authorized at an LFI with which the User already has a relationship.

The requirements for the authorization of consent at the LFI are reflected in the narrative below.

1.2 Step 2: Authorize Insurance Data Sharing Consent

For any operations that include Data Sharing the TPP MUST:

• Request the User to authorize the consent. Please refer to the Authentication and Authorization page to review the supported Authorization Flows.

• Construct a Rich Authorization Request (https://www.rfc-editor.org/rfc/rfc9396) with the authorization_details populated with the User’s consent

• Include an insurance consent with all the REQUIRED data permissions that the User intends to provide to the TPP.

• Include a UUID v4 as the ConsentId as a unique identifier for the insurance consent.

A TPP MAY be a broker for data to other parties, so it is valid for a User to have multiple consents for the same resource(s), with different consent or authorization parameters agreed upon.

1.2.1 Security and Access Control

Authorization Code Grant

The TPP MUST use an Authorization Code grant to obtain an Access Token to access all API resources provided under an Insurance Data Sharing consent.

Client Credentials Grant

The TPP MUST use Client Credentials grant to obtain an Access Token to invoke Insurance Quote operations on behalf of the User.

The User MUST NOT be redirected to an LFI to authorize consent for an Insurance Quote operation.

1.3 Step 3: Access Data

1.2.1 Request Data

The TPP MUST have a valid Access Token from the OFP authorization server, granted under the correct scope for Insurance Data Sharing or Quotes.

The TPP MUST use the Access Token to retrieve User data or invoke Insurance Quote operations at the OFP resource server.

The OFP MUST perform Access Token introspection, ensuring the Access Token:

• has not expired.

• has the correct scope.

• for Data Sharing, has been granted against a consent that is in a valid state for access.

The OFP must forward the request to the LFI, enriching the request with appropriate session metadata based on the implementation requirements of the OFP.

The LFI MUST return an API response when provided with a valid request from the OFP.

The OFP MUST return an API response when provided with a valid access token request from the TPP.

2. Examples

The following are non-normative examples of API access and usage of the Insurance Information API.

2.1 The TPP Redirects the User to Authorize Insurance Consent

Where the User and the TPP have agreed consent for Data Sharing a consent must be created, submitted to the OFP, and then authorized by the User at the LFI at which their insurance policies are held.

2.1.1 Request: TPP Uses Rich Authorization Request via a PAR (Pushed Authorization Request) Endpoint with the OFP to Obtain a Request URI

The Rich Authorization Request (RAR) request body is a JWT-Secured Authorization Request. A JAR is a signed JSON Web Token (JWS) that includes the following properties:

• kid is a valid signing key ID for the TPP on the Open Finance Directory.

• iss is client id (UUID v4, optionally prefixed with a URI where the client is federated by the Trust Framework).

• state is a UUID v4 value.

• response_type MUST be code.

• redirect_uri is the TPP’s redirect URI.

The authorization_details property contain the User’s insurance consent details, and a UUID v4 which is a unique identifier for the insurance consent.

The sample below shows the content of the authorization_details property, together with the content of the JAR, as a JSON object. This data will be encapsulated as a JWS when serialized, so a JSON example is provided for simplicity.

Permissions to access multiple insurance types, each with different permissions, are supported in the consent.

Create the RAR Request using the signed JWT, and create a Client Assertion using the private_key_jwt Client Authentication method described in OpenID Connect and specified in the FAPI 2.0 Security Profile.

The PAR request body, shown below, includes:

• The Client Assertion Type (client_assertion_type), which must be set to the value shown in the example.

• The Client Assertion (client_assertion).

• The RAR, encapsulated by the JAR (request)

2.1.2 Response: The OFP Provides the Request URI for the TPP

If the PAR request is successfully validated the request_uri parameter is returned, which must be used in the redirection to the LFI.

Header

2.2 The TPP Redirects the User to Their LFI with the Request URI to Authorize the Consent

2.3 The User Authorizes Consent at the LFI

Please refer to the API Hub documentation for the steps implemented by the LFI to indicate consent authorization by the User.

2.4 The LFI Returns an Authorization Code to the TPP

Header

2.5 The TPP Exchanges the Authorization Code for an Insurance API Access Token with the OFP

Header

Payload

2.6 The OFP Returns an Access Token, Refresh Token, and ID Token to the TPP

The authorization_details from the PAR request payload is returned in the body of the response from the Token endpoint (example uses an empty payload for brevity).

Header

Payload

The TPP can now request insurance policy information using the access token.

2.7 Get a List of Insurance Policies

The example Data Sharing use Motor Insurance as an example.

All insurance types use the same API operation signature, as described in the Insurance OpenAPI description, which should be used as reference.

2.7.1 Request: Insurance Policies Resource

Header

2.7.2 Response: Insurance Policies Resource

Header

Payload

2.8 Get an Insurance Policy

2.8.1 Request: Insurance Policy Resource

Header

2.8.2 Response: Insurance Policy Resource

Header

Payload

The example below is a reduced for the sake of brevity. Data will be returned based on the permissions granted in the consent.

Please refer to the OpenAPI description for properties of the response.

2.9 Get Customer Payment Details

2.9.1 Request: Customer Payment Details Resource

Header

2.9.2 Response: Customer Payment Details Resource

Header

Payload

2.10 Create an Insurance Quote

The TPP will send each the Insurance Quote request to all LFI instances at the OFP that the User has selected or are in scope to provide a response.

TPPs require an Access Token from each LFI instance at the OFP.

TPPs can use existing policy data to construct the quote request if a User has consented to Insurance Data Sharing access.

2.10.1 Request: Access Token with Client Credentials Grant

Header

Payload

2.10.2 Response: Access Token

Header

Payload

2.10.3 Request: Create an Insurance Quote

Header

Payload

2.10.4 Responses: Create an Insurance Quote

2.10.2.1 An Insurance Quote has been created and returned to the TPP

Header

Payload

2.10.2.2 A quote cannot be provided by the LFI

Header

2.11 Accept an Insurance Quote

2.11.1 Request: Accept an Insurance Quote

Header

Payload

The payload for the patch operation MUST be a JWS, signed with the appropriate key.

The Insurance Quote request payload can optionally contain a Subscription object, allowing the TPP to receive Event Notifications when the QuoteStatus changes.

2.11.2 Response: Accept an Insurance Quote

Header

2.12 Create an Insurance Policy from a Quote

2.11.1 Request: Create an Insurance Policy from Quote

Header

Payload

2.11.2 Response: Create an Insurance Policy from Quote

Header

Payload

3. Further Examples

3.1 The TPP Queries the Insurance Resource for the Status after a User has Authorized the Consent

3.1.1 Request: Retrieve an Insurance Consent

Header

3.1.2 Response: Retrieve an Insurance Consent

Header

Payload

3.2 The TPP Requests the List of Insurance Policies Using an Expired Access Token

3.2.1 Request: insurance-policies collection

Header

3.2.2 Response: 401 Unauthorized

Header

3.3 Webhooks

The OFP supports Webhooks for Insurance Data Sharing consent changes and Insurance Quote status changes.

A general guide to Webhooks is shown in the sections below.

3.2.1 The TPP Creates an Insurance Consent Request with a Webhook Subscription

3.2.1.1 Request: Insurance Consent and Webhook Subscription

Payload

3.2.2 The TPP updates a Webhook Subscription preference with the OFP

3.2.2.1 Request: Subscribe to Webhook events

Header

Payload

3.2.2.2 Response: Webhook events activated

Header

3.2.3 The TPP unsubscribes their Webhook Subscription with the OFP

3.2.2.1 Request: Deactivate Webhook events

Header

Payload

3.2.2.2 Response: Webhook events deactivated

Header

3.2.4 The TPP receives data from the OFP (specific to the consent and permissions) via its Webhook

3.2.3.1 The OFP generates a Self Signed JWT Authorization Token for Client Authentication with the TPP.

This JWT Authorization Token MUST be set in the Authorization Header.

Payload

3.2.3.2 Request: OFP publishes signed/encrypted data to the registered Webhook Url provided by the TPP

The example below shows a signed and encrypted payload with the JWT Authorization Token set in the Authorization Header.

Header

The payload is a signed and encrypted payload. The JWE contains a JWS, which contains a JSON payload.

Payload

The decrypted payload of the JWS, without the signature, is shown in the example below. The example JSON is abridged for brevity.

3.2.3.3 Response: TPP validates the Self Signed JWT Authorization Token from LFI, stores data, and acknowledges a successful response to the OFP

Header

5. OpenAPI Specification

See the Insurance OpenAPI page.

6. Notes

• TPP MUST request the ReadInsurancePolicies permission code to ensure they can read InsurancePolicyId values required to retrieve insurance policies. ReadInsurancePolicies must be request for each insurance type for which access is required.

• Customer payment details require the ReadCustomerPaymentDetails permission and must be specifically requested using the GET /insurance-policies/{InsurancePolicyId}/payment-details operation. This is to ensure a separation of concerns between the main body of data and the payment details.

7. Security

A insurance scope is used for accessing the insurance endpoints.