LFI · Trust Framework · API

API Guide 2 min read

The Trust Framework directory provides a set of APIs that enable Applications within the framework to communicate and exchange data.

This guide explains how a registered Application can:

Retrieve all registered Organisations
Filter those Organisations to identify TPPs
Retrieve the associated Software Statements for each TPP

These steps can be used, for example, to generate a report that cross-references Organisations with their corresponding Software Statement applications.

01 Prerequisites

What you need before calling the Trust Framework API

Before calling the Trust Framework API, ensure the following requirements are met:

Registered Application — the application must be created within the Trust Framework.
Valid Transport Certificate — an active transport certificate must be issued and registered in the Trust Framework to establish secure mTLS communication.

02 API Sequence Flow

End-to-end Trust Framework API call

Sequence diagramTrustFramework - ExampleClick to expand

03 Step 1

Obtain an Access Token

The directory uses the OAuth 2.0 client credentials grant. POST to the directory's token endpoint, presenting your transport certificate over mTLS:

typescript

import https from 'node:https'
import fs from 'node:fs'

const CLIENT_ID  = process.env.CLIENT_ID!
const AUTH_BASE  = process.env.DIRECTORY_AUTH_BASE!
// production:  https://matls-auth.directory.openfinance.ae
// sandbox:     https://matls-auth.sandbox.directory.openfinance.ae

const agent = new https.Agent({
  cert: fs.readFileSync(process.env.TRANSPORT_CERT_PATH!),
  key:  fs.readFileSync(process.env.TRANSPORT_KEY_PATH!),
})

const params = new URLSearchParams({
  grant_type: 'client_credentials',
  scope:      'directory:software',
  client_id:  CLIENT_ID,
})

const tokenResponse = await fetch(`${AUTH_BASE}/token`, {
  method:  'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body:    params.toString(),
  // @ts-expect-error — Node fetch accepts agent via undici dispatcher or a polyfill
  agent,
})

const { access_token } = await tokenResponse.json()

See the POST /token API reference for the full request and response schema.

04 Step 2

List all Organisations

With the token, call the /organisations endpoint to retrieve every organisation registered in the directory:

typescript

const API_BASE = process.env.DIRECTORY_API_BASE!
// production:  https://matls-api.directory.openfinance.ae
// sandbox:     https://matls-api.sandbox.directory.openfinance.ae

const orgsResponse = await fetch(`${API_BASE}/organisations`, {
  headers: { Authorization: `Bearer ${access_token}` },
  // @ts-expect-error
  agent,
})

const organisations: Organisation[] = await orgsResponse.json()

Key response fields

Field	Type	Description
`OrganisationId`	string	Unique identifier for the organisation — used in subsequent calls
`OrganisationName`	string	Human-readable name of the organisation
`Size`	string ≤ 255 chars, `^[^<>]*$`	Organisation type — `"TPP"` for Third Party Providers, `"LFI"` for Licensed Financial Institutions. Use this field to filter results to TPPs only.
`Status`	string	Registration status, e.g. `Active`
`CreatedOn`	string (ISO 8601)	Date the organisation was registered

See the GET /organisations API reference for the full response schema.

05 Step 3

Filter for TPPs

The /organisations response includes both LFIs and TPPs. Use the Size field to narrow the list to TPPs only before iterating:

typescript

const tpps = organisations.filter((org: Organisation) => org.Size === 'TPP')

06 Step 4

Retrieve Software Statements

For each TPP from Step 3, call the /softwarestatements sub-resource using its OrganisationId:

typescript

interface SoftwareStatement {
  SoftwareStatementId: string
  SoftwareClientName:  string
  Status:              string
  // … additional fields
}

const allSoftwareStatements: (SoftwareStatement & { OrganisationId: string; OrganisationName: string })[] = []

for (const org of tpps) {
  const orgId   = org.OrganisationId
  const orgName = org.OrganisationName ?? 'Unknown'

  const ssResponse = await fetch(
    `${API_BASE}/organisations/${orgId}/softwarestatements`,
    {
      headers: { Authorization: `Bearer ${access_token}` },
      // @ts-expect-error
      agent,
    }
  )

  const statements: SoftwareStatement[] = await ssResponse.json()

  for (const ss of statements) {
    allSoftwareStatements.push({ ...ss, OrganisationId: orgId, OrganisationName: orgName })
  }
}

Key response fields

Field	Type	Description
`SoftwareStatementId`	string	Unique identifier for the Software Statement
`SoftwareClientName`	string	Human-readable name of the client application
`Status`	string	Status of the Software Statement, e.g. `Active`
`SoftwareRoles`	string[]	Roles assigned to this application (e.g. `BDSP`, `BSIP`)
`OrganisationId`	string	The owning organisation (not always returned inline — join from Step 2)

See the GET /softwarestatements API reference for the full response schema.