Headless Heimdall Auth Server 2 min read
The Headless Heimdall Auth Server is an API provided by the API Hub that powers the consent authorisation journey. It shields your authorisation server from the complexity of raw OIDC and FAPI 2.0 — your system calls three endpoints at the appropriate points in the customer journey and the API Hub handles the rest.
Per-environment Headless Heimdall hosts
| Environment | URL |
|---|---|
| Pre-production | https://hh.{lfiCode}.preprod.apihub.openfinance.ae |
| Production | https://hh.{lfiCode}.apihub.openfinance.ae |
Where {lfiCode} is the LFI Code assigned during API Hub onboarding.
C3-hh-cm-client over mTLS, optionally JWT-signed
All requests to the Headless Heimdall Auth Server MUST be made using the C3-hh-cm-client application registered in the Trust Framework. This is the same client used to call the Consent Manager.
Requests MUST be made over mutual TLS using the C3 transport client certificate. If your API Hub is configured for JWT Auth, you MUST also include a signed JWT in the Authorization header, signed with the Sig4 signing key.
See Connectivity & Certificates for the full certificate mapping, and Creating the C3-hh-cm-client Application for setup instructions.
Three endpoints, one FAPI 2.0 authorisation code flow
When a TPP initiates a consent request, the API Hub creates the consent record and redirects the end user to your authorisation endpoint. From that point, your authorisation server interacts with the Headless Heimdall Auth Server to coordinate the FAPI 2.0 authorisation code flow:
- GET
/auth— Your authorisation server calls this at the start of every authorisation code grant. The API Hub validates the FAPI/OIDC request and returns the interaction context and the decoded consent details. Your system uses these details to present the consent to the end user for approval. - POST
/auth/{interactionId}/doConfirm— After the end user has authenticated and authorised the consent, your system calls this to complete the interaction. The API Hub updates the consent state and issues tokens to the TPP. - POST
/auth/{interactionId}/doFail— If authentication fails or the end user rejects the consent, your system calls this to end the interaction. The API Hub initiates an error redirect back to the TPP.
During the authorisation journey, your system will typically also call the Consent Manager to read the full consent object and update its state. Both APIs work together to complete the journey.
For the full API flow, see the Consent Journey API Guide.
Where to find the endpoints
The full API reference for each endpoint is available in the sidebar under API Reference. Use GET/hello-mtls to verify your mTLS connectivity before calling other endpoints.