openapi: 3.0.1
servers:
- url: https://<your-ozone-hh-server>
info:
title: Headless Heimdall APIs
contact:
name: Ozone Financial Technology Limited
description: |
This document provides the OAS3 specification for the APIs provided by Headless Heimdall.
These APIs are implemented by Ozone and should be called by the financial institution at the end of their authorization journeys.
The interface allows for an financial institution to develop the user interface for customers without
having to deal with the complexities of OIDC and FAPI and without having to gain a
thorough understanding of the constraints placed by FAPI.
__Version 2.2 Release 2024.34
The interface consists of end-points
- The __Headless Authorization End-point__ `GET /auth` should be called by the financial institution at the
begining of an authorization code grant. This is typically immediately after it receives an authorization
request from a TPP
- The __Confirmation End-point__ `POST /auth/:interactionId/doConfirm` should be called by the
financial institution to notify Heimdall that an interaction has completed successfully.
- The __Failure End-point__ `POST /auth/:interactionId/doFail` should be called by the financial institution
to notify Heimdall that the interaction has failed.
#### Changes version:in Release 2024.34.1
tags: - name: headless-heimdall * paths:Refactored Security Scheme /auth:Objects to use common definitions get:across all API Hub APIs
tags:
* Implemented -the headless-heimdallcorrect Security Requirements for this API description, summary:reflecting Startsecurity anpatterns authorisationavailable interactionin API Hub
descriptionversion: |Version 2024.34.1
tags:
- name: headless-heimdall
security: The
Headless Authorization End-point should{}
be called by- theOzoneConnectJwtAuth: financial[]
institution
atpaths:
the beginning of/auth:
the get:
interaction. tags:
The end-point validatesheadless-heimdall
all the parameters that are passed tosummary: itStart toan ensures that theauthorisation interaction
description: |
The Headless authorizationAuthorization requestEnd-point isshould FAPIbe compliant,called valid,by correctlythe signedfinancial andinstitution hasat the beginning of the
appropriate client_id, redirect_uri etcinteraction.
The end-point respondsvalidates withall onethe ofparameters thethat threeare outcomes:passed to it to ensures that the
- __Success__: The end-point returns a status 200. The body contains a JSON object with the
interaction and all the query parameters extracted from the OIDC request object authorization request is FAPI compliant, valid, correctly signed and has the
appropriate client_id, redirect_uri etc.
The end-point responds with one of the three outcomes:
- __Success__: The end-point returns a status 200. The body contains a JSON object with the
interaction and all the query parameters extracted from the OIDC request object.
- __Non-redirectable failure__: This indicates a failure to verify that the end-point was called
through a valid OIDC client. The financial institution should render an error page and end the interaction.
- __Redirectable failure__: This indicates a failure where the end-point was called by a potentially valid OIDC client.
Headless Heimdall responds with a 303 redirect. The financial institution must respond to the TPP with the same redirect without any modifications.
- __Non-redirectable failure__: This indicates a failure to verify that the end-point was called
through a valid OIDC client. The financial institution should render an error page and end the interaction.### Processing a success response
There are three key fields in the success response that financial institutions are likely to be interested in:
- __Redirectable failure__`interaction.interactionId`: This indicatesis athe failureinteraction whereidentifier thethat end-pointshould wasbe calledused bywith
a potentially valid OIDC client. subsequent calls to Headless Heimdall respondswhen withthis aauthorization 303request redirect.is Thecompleted financialby institution must respond to the TPP with the same redirect without any modifications.the financial institution.
- `interaction.params.claims.id_token.openbanking_intent_id`: If this interaction is for ###a ProcessingUK aOBIE successconsent
response authorisation, Therethe areConsent threeId keyis fieldscontained in thethis successfield. responseThe that financial institutionsinstitution arecan likelyuse tothe beOzone interestedConsent in:Manager
API
- `interaction.interactionId`: Thisto isretrieve the interactionconsent
identifier
that should be used with - `tpp.directoryRecord`: Where Ozone is subsequentintegrated callswith toa HeadlessDirectory HeimdallService, whenthis thiscontains authorizationa requestrecord
is completed by the financial institution. of the TPP record as held on -the `interactionsdirectory.consentIdsList`: The structure of Consentthe Idrecord iswill containeddepend inon thisthe fielddirectory. TheDirectory financial institutionrecord canas useheld theby Ozone Consent Manager APIin base 64 encoded format.
to retrieve the### consentParameters
OAS3 - `tpp.directoryRecord`: Where Ozone is integrated withdoes not have a way to indicate a Directoryflexible Service,set thisof containsquery aparameters.
record
ofWhen thecalling TPPthis recordAPI, asthe heldfinancial oninstitution theshould directory.pass Theon structure ofall the record willquery dependparameters onor thehash directory.parameters Directoryreceived recordfrom asthe heldTPP
by Ozone in base 64 encoded format. in the authorization request.
### Parameters operationId: headlessAuthorization
OAS3 doesresponses:
not have a way to indicate a flexible set"200":
of query parameters. description: |
When calling this API, the financial institution should pass on all the queryThis parametersindicates orthat hashthe parameters received from thewere TPPsuccessfully validated.
in the authorization request. The financial institution should continue operationId:with headlessAuthorizationthe next stages of the interaction, keeping track responses:of the
"200": returned interactionId.
description: | content:
This indicates that the parameters were successfully validated.application/json:
Theschema:
financial institution should continue with the next stages of the interaction, keeping track of the $ref: '#/components/schemas/AuthSuccessResponse'
returned interactionId."303":
contentdescription: |
application/json: This indicates that the parameters were not successfully verified.
schema: However, there were no indications that the request originated $ref: '#/components/schemas/AuthSuccessResponse'
from an invalid client.
"303": The financial institution should respond description:to |the customer with a redirect This indicates thatto the URI returned by the parametersAPI
were not successfully verified. (including the query or hash However,parameters thereincluded werein nothe indicationsURL)
that
the request originated from an invalid client. "400":
description: The|
financial institution should respond to the customer with a redirect to the URIThis returnedindicates bythat the parameters APIwere not successfully verified.
(including the query orHeimdall hashcould parametersnot includedverify inthat the URL)request originated from a valid client.
"400": The financial institution description:should |render an error page.
This indicates that the parametersThe werefinancial notinstitution successfully verified.
__must not__ redirect back to the TPP.
Heimdall could not verifycontent:
that the request originated from a valid client. application/json:
The financial institution should render an errorschema:
page. The financial institution __must not__ redirect back to the TPP.
$ref: '#/components/schemas/AuthErrorResponse'
/auth/:interactionId/doConfirm:
post:
operationId: doConfirm
content: tags:
application/json: - headless-heimdall
summary: Ends an authorisation interaction schema:with a success response
description: |
$ref: '#/components/schemas/AuthErrorResponse' The Confirmation End-point should be security:called by the financial institution once the user interaction
- bearerAuth: [] /auth/:interactionId/doConfirm: has been completed post:and the resource owner has authorized access.
operationId:
doConfirm tags: The doConfirm call updates the interaction state generates -an headless-heimdallOIDC `code` and the rest of the
summary: Ends an authorisation interaction with a success response that should be returned to the description:TPP.
|
The financial institution Confirmationcan End-pointspecify shouldthe beset calledof byclaims theto financialbe institutionadded onceto the user interaction
id_token. Heimdall creates an
has been completedid_token andwith thethese resourceclaims owneralong haswith authorizedany access.claims required by FAPI and OIDC.
The doConfirm call updates the interactionHeimdall statereturns generatesa an303 OIDCwith `code`a andredirect theuri. restThis ofresource theowner should be redirected to this URI.
response that should be returned to the TPP.### Parameters
The financialrequest institutionbody can specifycontain an thearbitrary set of claims to be added to the id_token. Heimdall creates an
`application/x-www-form-urlencoded` name-value pairs.
These are added by Heimdall to the id_token. withThe claim thesename claimsis alongset withto anythe claimsparameter requiredname
by FAPI and OIDC. and the claim value to Heimdallthe returnsparameter avalue.
303
with a redirect uri. This resource owner should beClaim redirectednames toprefixed thisby URI`heimdall.` act as control parameters for the tokens that are ###produced.
Parameters These Theclaims requestare bodynot canadded containto an arbitrary set of `application/x-www-form-urlencoded` name-value pairs.
the id_token.
requestBody:
Thesecontent:
are added by Heimdall to the id_token. The claim name is set to the parameter name application/x-www-form-urlencoded:
schema:
and the claim value to the parameter value. type: object
Claim names prefixed by `heimdall.` act as control parameters for the tokens that areproperties:
produced. These claims are not added to the id_token."heimdall.suppressRefreshToken":
requestBody: contenttype: boolean
application/x-www-form-urlencoded: description: |
schema: type: object Suppresses the generation of a refresh token.
properties: If set "heimdall.suppressRefreshToken":
to true, a refresh token is not generated.
type: boolean If set to false, a refresh token is generated only if description:Heimdall |has been
Suppresses theconfigured generationto ofsupport athe refresh_token tokengrant type.
If setnot to truespecified, aHeimdall refreshtreats tokenthis isas not generatedfalse.
IfNote setthat tothis false,feature a*must refreshnot* tokenbe isused generatedfor onlyCBUAE
if
Heimdall has been "heimdall.accessTokenValidity":
configured to support the refresh_token grant type. type: integer
If not specified, Heimdall treats this as false. description: |
Note thatSpecifies this(in featureno *must not* be used for CBUAE
of seconds) how long the generated access token should be valid for.
"heimdall.accessTokenValidity": If not specified, the system default is used.
type: integer description:Note |that this feature *must not* be used for CBUAE
Specifies (in no of seconds) how long the generated access token should be valid for. "heimdall.refreshTokenValidity":
type: integer
If not specified, the system default is used. description: |
Note thatSpecifies this(in featurenumber *must not* be used for CBUAE
of seconds) how long the generated refresh token
"heimdall.refreshTokenValidity": should be valid for.
type: integer If not specified, the system default is used.
description: | Note that Specifiesthis (infeature number*must ofnot* seconds)be howused longfor theCBUAE
generated
refresh token additionalProperties: true
should beparameters:
valid for. - $ref: '#/components/parameters/interactionId'
responses:
If not specified, the system"303":
default is used. description: |
NoteHeimdall thatreturns thisa featureredirect *musturi not*that becontains usedan forauthorization CBUAEcode along with
additional additionalProperties:parameters trueas required by OIDC.
parameters: -In $ref: '#/components/parameters/interactionId'
responses:
case an internal error occurred while processing the request, heimdall returns
"303": an error parameter.
description: | In both cases, the Heimdallfinancial returnsinstitution amust redirect urithe thatresource containsowner anto authorization code along with
the redirect uri.
/auth/:interactionId/doFail:
post:
additional parameters as required byoperationId: OIDC.doFail
tags:
In case an- internalheadless-heimdall
error occurred while processing the request, heimdallsummary: returnsEnds an authorisation interaction with a failure response
an error parameter.description: |
The failure End-point should Inbe bothcalled cases,by the financial institution mustonce redirect the resource owner to the redirect uri.user interaction
security:has been completed and has resulted in a failure -to bearerAuth: []gain access.
/auth/:interactionId/doFail: post: (e.g. when the user declines to operationId:authorise, doFaildoes not provide the appropriate credentials etc.)
tags:
-The headless-heimdalldoFail call updates the interaction state, generates summary:an EndsOIDC an`error` authorisationand interactionthe withrest aof failurethe
response description:response |that should be returned to the TPP.
The failure End-point should be called by theThe financial institution oncecan specify the user`error` interactionand `error_description` as x-www-form-urlencoded parameters.
has been completed and has resultedHeimdall inreturns a failure303 with toa gainredirect accessuri. This resource owner should be redirected to this (e.gURI.
when
the user declines to authorise, does notrequestBody:
provide the appropriate credentials etc.) content:
The doFail call updates the interaction state, generates an OIDC `error` and the rest of the application/x-www-form-urlencoded:
schema:
response that should be returned to the TPP. type: object
The financial institution can specify the `error` and `error_description` as x-www-form-urlencoded parameters.properties:
Heimdall returns a 303 with aerror:
redirect uri. This resource owner should be redirected to this URI. requestBodytype: string
content: application/x-www-form-urlencodeddescription: |
schema: An OAuth2.0 or OIDC error
type: object properties:error_description:
type: string
errorparameters:
- $ref: '#/components/parameters/interactionId'
typeresponses:
string "303":
description: |
Heimdall returns a redirect uri that contains an authorization code Analong OAuth2.0with
or OIDC error additional parameters as required by OIDC.
error_description: In case an internal error occurred while processing type:the stringrequest, heimdall returns
parameters: an error -parameter.
$ref:
'#/components/parameters/interactionId' responses: In both cases, the financial "303":institution must redirect the resource owner to the redirect uri.
descriptioncomponents:
| schemas:
AuthSuccessResponse:
Heimdall returnstype: aobject
redirect uri that contains an authorization codeproperties:
along with interaction:
additional parameters as required by OIDC.type: object
properties:
In case an internal error occurred while processing the request, heimdall returnsinteractionId:
an error parameter.type: string
In both cases,description: the financial institution must redirect the resource owner to the redirect uri.An identifier for this interaction
securityparams:
- bearerAuth: [] components: schemasdescription: |
AuthSuccessResponse: type: object Query parameters properties:unbunbled from the original authorization request.
interaction: type: object This includes both query parameters and hash parameters.
properties:
interactionId: This also includes parameters extracted from the OIDC request object.
type: string type: object
description: An identifier for this interaction properties:
params: client_id:
description: | description: |
Query parameters unbunbled from the original authorization request. The clientId that the caller Thisclaims includesto bothhave.
query
parameters and hash parameters. At Thisthis alsostage, includesHeimdall parametershas extractedverified fromthat the OIDCclient requestid objectexists.
type: object type: string
properties: response_type:
client_id: type: string
description: | scope:
The clientId that the caller claims totype: have.string
request:
At this stage, Heimdall has verified that the client id exists. type: string
type: string scopes:
response_type: description: |
type: string The requested scope in the authorization request broken down into an scope:array
type: array
string requestitems:
type: string
scopesclaims:
description: |
The requested scope in the authorization request broken down into an arrayclaims in the authorization request.
type: arrayobject
itemsadditionalProperties: true
additionalProperties: true
type: string claims:
claims: type: object
descriptionstatus:
| type: string
The requested claims in the authorization request. consentId:
type: objectstring
description: An identifier for additionalProperties: trueconsent
additionalPropertiesdeprecated: true
claimsconsentIdsList:
type: objectarray
status: description: |
type: string consentId:
Consent Ids associated with the interaction.
type: string Note that RAR requests may contain multiple consents. However, support description:for Anthis identifieris fornot consentrequired in the CBUAE 2024 standards and LFIs may consider
deprecated: true that this array consentIdsList:may have a single value.
type: array items:
description: | type: string
tpp:
Consent Ids associated with the interaction. $ref: "#/components/schemas/tpp"
AuthErrorResponse:
Notetype: thatobject
RAR requests may contain multiple consents. However,properties:
support for this is not required in the CBUAEnoRedirect:
2024 standards and LFIs may consider type: boolean
error:
that this array may have a single value. type: string
itemserror_description:
type: string
type: string interactionId:
tpp: type: string
$ref: "#/components/schemas/tpp"tpp:
AuthErrorResponsetype: object
type description: object|
properties: The TPP record as held by Ozone.
noRedirect:
If Ozone type:TPP booleanConnect has been integrated into a directory, the `directoryRecord` error:provides the TPP's directory record as held by Ozone in base type:64 stringencoded format.
error_descriptionrequired:
- clientId
type: string - orgId
interactionId: - softwareStatementId
type: string - tppName
tpp:
typeproperties:
object descriptionclientId:
| The TPPtype: recordstring
as held by Ozone. description: The clientId Iffor Ozonethe TPP Connect has been integrated into a directory, the `directoryRecord` provides the TPP's directory record as held by Ozone in base 64 encoded format.as issued by Ozone
orgId:
type: string
required: description: The organization id for the TPP
-
clientId softwareStatementId:
- orgId -type: softwareStatementIdstring
- tppName description: The organization id for the TPP
properties:
clientIdtppName:
type: string
description: The clientIdname forof the TPP as
issued
by Ozone orgIddirectoryRecord:
type: string
description: The organizationlatest idcopy forof the TPP directory record if the TPP has registered with a directory
softwareStatementId:
parameters:
interactionId:
type: string name: interactionId
descriptionin: query
The organization id for the TPP schema:
tppNametype: string
type: string
required: true
description: TheIdentifier namefor of the TPPinteraction
securitySchemes:
directoryRecordOzoneConnectJwtAuth:
description: |
type: string Communications between the API Hub and the LFI Ozone description:Connect Theimplementation latestare copysecured ofusing the TPP"JWT directoryAuth" recordmechanism, ifwhere the TPP has registered with Client presents a signed JSON Web Token as a directorycredential.
parameters: interactionId:
name: interactionId The Server MUST verify the signature in: queryorder to authenticate the Client.
schema: Please note type:that stringthe value of the `scheme` parameter is required:not truea registered HTTP Authentication Scheme, to indicate description:it Identifieris forspecific theto interactionOzone Connect. Please refer to securitySchemes:API Hub documentation for further bearerAuth:details.
type: http
scheme: bearer
bearerFormat: JWTOzone-Connect-JWT-Auth | 