Consent Journey — API Guide 6 min read

const HH_BASE = process.env.HEADLESS_HEIMDALL_BASE_URL!
// e.g. 'https://hh.{lfiCode}.preprod.apihub.openfinance.ae'

// Pass through all query parameters received at your authorization endpoint
const queryString = new URLSearchParams({
  client_id: req.query.client_id,
  response_type: req.query.response_type,
  request_uri: req.query.request_uri,
}).toString()

const authResponse = await fetch(`${HH_BASE}/auth?${queryString}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
  },
  // mTLS with C3 transport certificate
  // agent: new https.Agent({ cert: c3TransportCert, key: c3TransportKey }),
})

if (authResponse.status === 303) {
  // Redirectable failure — redirect the end user to the URI in the Location header without modification
  return res.redirect(authResponse.headers.get('location'))
}

if (authResponse.status === 400) {
  // Non-redirectable failure — render an error page to the end user
  return res.status(400).render('auth-error')
}

const authData = await authResponse.json()

// Extract the interactionId and consentId — store both for subsequent calls
const interactionId = authData.interaction.interactionId
const consentId = authData.interaction.consentIdsList[0]

const CM_BASE = process.env.CONSENT_MANAGER_BASE_URL!
// e.g. 'https://cm.{lfiCode}.preprod.apihub.openfinance.ae'

const consentResponse = await fetch(`${CM_BASE}/consents/${consentId}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
  },
  // mTLS with C3 transport certificate
  // agent: new https.Agent({ cert: c3TransportCert, key: c3TransportKey }),
})

const consent = await consentResponse.json()

// The consent object contains the full consent details:
// - consent.data.consentBody.Data.Permissions (for data sharing)
// - consent.data.consentBody.Data.ExpirationDateTime
// - consent.data.consentBody.Data.PersonalIdentifiableInformation (if encrypted PII is present)

// PATCH /consents/{consentId} — authorize the consent
await fetch(`${CM_BASE}/consents/${consentId}`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 'Authorized',
    psuIdentifiers: {
      // Your internal end user identifier — the structure is flexible,
      // use whatever fields your institution uses to identify the customer
      userId: authenticatedUser.id,
    },
    accountIds: [
      // Account IDs the end user selected for this consent
      // For Bank Data Sharing: one or more accounts
      // For Bank Service Initiation: exactly one debtor account
      // For Insurance Data Sharing: omit accountIds — use insurancePolicyIds instead
      'account-id-1',
      'account-id-2',
    ],
    authorizationChannel: 'App', // 'App' or 'Web'
  }),
  // agent: new https.Agent({ cert: c3TransportCert, key: c3TransportKey }),
})

// POST /auth/{interactionId}/doConfirm — complete the authorization
const confirmResponse = await fetch(
  `${HH_BASE}/auth/${interactionId}/doConfirm`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    redirect: 'manual', // capture the 303 redirect
    // agent: new https.Agent({ cert: c3TransportCert, key: c3TransportKey }),
  }
)

// The API Hub responds with a 303 redirect back to the TPP
const redirectUri = confirmResponse.headers.get('location')

// Redirect the end user to the TPP — journey complete
res.redirect(redirectUri)

// PATCH /consents/{consentId} — reject the consent
await fetch(`${CM_BASE}/consents/${consentId}`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 'Rejected',
    psuIdentifiers: {
      userId: authenticatedUser.id,
    },
    // Do NOT include accountIds for rejected consents
    authorizationChannel: 'App', // 'App' or 'Web'
  }),
  // agent: new https.Agent({ cert: c3TransportCert, key: c3TransportKey }),
})

// POST /auth/{interactionId}/doFail — end the authorization with a failure
const failResponse = await fetch(
  `${HH_BASE}/auth/${interactionId}/doFail`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      error: 'access_denied',
      error_description: 'The user rejected the consent',
    }),
    redirect: 'manual', // capture the 303 redirect
    // agent: new https.Agent({ cert: c3TransportCert, key: c3TransportKey }),
  }
)

// The API Hub responds with a 303 redirect back to the TPP with error parameters
const redirectUri = failResponse.headers.get('location')

// Redirect the end user to the TPP — journey ended
res.redirect(redirectUri)