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

Keys and Certificates 4 min read

To operate within the ecosystem, your application must use certificates issued and stored within the Trust Framework. There are three types of certificates, each serving a distinct security function.

01 Certificate Types

Transport, Signing, and Encryption

1. Transport Certificate — Required

Used for mutual TLS (mTLS) to authenticate your client (application) when making API requests.

  • Purpose: Secure transport and client authentication
  • Usage: mTLS handshake for all API calls
  • Presented to: API providers during connection

2. Signing Certificate — Required

Used to digitally sign JWTs your application sends — such as client assertions, request objects, etc.

  • Purpose: Proving integrity and authenticity of signed payloads
  • Usage: Signing the contents of JWTs

3. Encryption Certificate — Optional (required for participants subscribing to receive events)

Used to encrypt data such as an event.

  • Purpose: Ensuring only your application can read sensitive data
  • Usage: Decrypting encrypted responses

Each certificate plays a critical role in securing communication, asserting identity, and protecting data in transit. Once you understand the different certificate types, you can generate the required keys and CSRs according to the Trust Framework specifications.

02 Key and Certificate Requirements

2048-bit RSA, SHA-256 CSR, and the required subject fields

Keys and certificates within the Trust Framework (TF) must meet the following requirements:

  • 2048-bit RSA private key (unencrypted)
  • A corresponding Certificate Signing Request (CSR) signed with SHA-256
  • CSR subject fields must include:
    • C → Country — must be set to AE (United Arab Emirates)
    • O → Organization — must equal the Organization's legal name in the Trust Framework
    • OU → Organizational Unit — must equal the Organization's ID in the Trust Framework
    • CN → Common Name — must equal the application's Client ID (the UUID assigned by the Trust Framework when the application was created)

Generating the Private Key and CSR

The Trust Framework provides an example using OpenSSL to generate:

  • A private key file (.key)
  • A Certificate Signing Request file (.csr)

Example:

opensslbash
openssl req -new -newkey rsa:2048 -nodes \
  -keyout <UUID>.key \
  -out <UUID>.csr \
  -subj "/C=AE/O=<LegalName>/OU=<OrganizationId>/CN=<UUID>" \
  -sha256

Replace LegalName and OrganizationId with your organisation's details from the Trust Framework. Replace UUID with your application's Client ID — the UUID assigned when the application was created (see Creating an Application). Equivalent cryptographic tools may be used, provided all requirements above are met.

The .csr file (Certificate Signing Request) must be uploaded to the Trust Framework. The .key file (Private Key) must be kept secure and must never be shared. More information on private key handling and security requirements can be found here.

03 Walkthrough

Creating a certificate in the Trust Framework portal

  1. Navigate to App Certificates

    1. Open your application in the Trust Framework.
    2. Click App Certificates.
    3. Click + New Certificate.

  2. Select the certificate type

    1. Select the type of certificate you want to generate: Transport, Signing, or Encryption. You will need to repeat this process for each type.

  3. Generate the private key and CSR

    1. Generate your private key (.key) and Certificate Signing Request (.csr).
    2. Confirm that the CSR has been generated successfully before proceeding.
    Production environments

    The OpenSSL command shown is intended for demonstration and testing only. In production, private key generation and CSR creation must be performed within your HSM or equivalent secure key management infrastructure, in accordance with your institution's security policies.

  4. Upload the CSR

    1. Click Upload your CSR and select the .csr file generated in the previous step.

  5. Download the certificate

    1. Once the Trust Framework processes the CSR, your certificate is ready. Download the .pem certificate file.
    2. You now have the .pem / .key pair. Store your private key securely — it must never be shared. See Secure Management for requirements.
Renewing a certificate before it expires

Certificates are valid for 13 months and must be rotated before they expire to avoid breaking services. As a TPP you hold the private key for all of your application certificates, so you rotate each of them yourself. See Certificate Rotation for the best-practice guide covering reminders, the safe overlap pattern, and transport- and signing-specific steps.

04 Finding Your Key ID (kid)

The kid value used in every signed JWT

Once your certificate is issued, the Trust Framework assigns it a Key ID (kid). This value must be included in the kid header of every JWT signed with the corresponding private key.

Key ID (kid) location on the certificate detail page in the Trust Framework
Key ID (kid) location on the certificate detail page in the Trust Framework
Where to find it later

Your kid is always visible on the certificate detail page. Navigate to your Application → App Certificates → select the certificate. Copy the Key ID exactly as shown — it is case-sensitive. See Message Signing for how the kid value is used in the JWT header.

You will need a separate kid for each certificate type (Transport, Signing, Encryption). When signing JWTs, always use the kid of your Signing certificate.