How to Decrypt PII 5 min read

Pattern A — decrypt at consent creation

/consent/action/validate is called by the API Hub synchronously, inside the TPP’s PAR request and before the consent exists. The PII is at most seconds old, and the post consent event fires at the same moment in the lifecycle. Nothing can have rotated in between, so:

• The kid in the JWE header names an Enc1 key you currently hold.
• If you verify the TPP’s signature, the TPP’s active JWKS is sufficient.
• The JWS exp, iat and nbf claims can be evaluated against the current time, because now is the moment of signing. Library defaults are correct here.

Pattern B — decrypt later

Everywhere else is “later”. The authorisation journey already is: between the TPP creating the consent and the customer authenticating on your platform there can be a redirect the customer does not follow immediately, an app switch, an abandoned login resumed later. Payment execution is later still — a multi-payment consent executes against the same PII for as long as the consent lives. Three things follow.

• Your own Enc1 key. The JWE was encrypted to whichever Enc1 public key you had published when the consent was created. The recommended Server ENCKEY certificate type does not expire, so routine rotation is avoided — but if you do replace Enc1, you MUST retain the retired private key for as long as consents encrypted under it remain in force. Step 1 below exists for exactly this reason: resolve the private key from the kid, never from “the current one”.
• The TPP’s signing key — only if you verify the signature. TPPs rotate signing keys freely and without notice, and a rotated kid leaves the active JWKS. Resolve the kid against the active set and then against the inactive/ set, and pin PS256 yourself — published JWKS entries carry no alg.
• The timing claims. exp, iat and nbf on the PII JWS bound the PAR submission window — the moment the TPP created the consent — not the moment you are decrypting. On a long-lived consent they will normally have lapsed. Evaluate them against the consent’s CreationDateTime, or do not evaluate them at all. Whether the consent is still usable today is answered by the API Hub’s consent validation on every request, not by a claim inside the PII.

Decrypt the JWE using your Enc1 private key. The result is the inner JWS (signed JWT):

import { compactDecrypt, importPKCS8 } from 'jose'

const privateKeyPem = myKeyStore.getPrivateKeyPem(kid)
const privateKey = await importPKCS8(privateKeyPem, 'RSA-OAEP-256')

const { plaintext } = await compactDecrypt(piiJweString, privateKey)
const jwsString = new TextDecoder().decode(plaintext)

After decrypting, the LFI MUST validate the PII payload against the relevant OpenAPI schema. The PII has not been validated by the API Hub — schema validation is the LFI's responsibility.

Obtaining the OpenAPI specification

The OpenAPI YAML files are the source of truth for PII schemas. They are maintained in the canonical specification repository:

Nebras-Open-Finance/api-specs

Spec files are located under dist/ by category:

Validating against the schema

Extract the relevant components/schemas entry from the YAML file and validate the decrypted PII payload against it. The PII schemas in the OpenAPI specification already declare the constraints needed for validation:

• additionalProperties: false is set at every level of the PII schema — any unexpected fields will cause validation to fail.
• required arrays are declared on sub-schemas (e.g. CreditorAccount is required on each creditor entry, SchemeName and Identification are required on account objects) — missing mandatory fields will cause validation to fail.
• enum constraints restrict values to allowed options (e.g. SchemeName must be IBAN).
• $ref pointers link to nested schemas (creditor, debtor, risk). For validation to work correctly, all components/schemas entries from the spec MUST be registered with the validator so that $ref pointers resolve.

When you register the full set of component schemas and compile the PII schema, standard JSON Schema validators (ajv for Node.js, jsonschema for Python) will enforce all of these constraints automatically. No custom validation logic is needed for schema conformance — the OpenAPI spec is the single source of truth.

The following example shows how to validate a domestic payment PII at consent time:

import Ajv from 'ajv'
import { load } from 'js-yaml'
import { readFileSync } from 'fs'

// 1. Load the OpenAPI spec and extract the PII schema
const spec = load(
  readFileSync('uae-api-hub-consent-manager-openapi.yaml', 'utf-8')
) as Record<string, any>

const piiSchema =
  spec.components.schemas[
    'AEBankServiceInitiationRichAuthorizationRequests.AEDomesticPaymentPII'
  ]

// 2. Build a validator — register all component schemas so $ref resolves
const ajv = new Ajv({ allErrors: true, strict: false })

for (const [name, schema] of Object.entries(spec.components.schemas)) {
  ajv.addSchema(schema as object, `#/components/schemas/${name}`)
}

const validate = ajv.compile(piiSchema)

// 3. Validate the decrypted PII payload
function validatePIISchema(piiPayload: Record<string, unknown>): void {
  const valid = validate(piiPayload)
  if (!valid) {
    const errors = validate.errors?.map(e => `${e.instancePath} ${e.message}`)
    throw new Error(`PII schema validation failed:\n${errors?.join('\n')}`)
  }
}