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 an API description in [OpenAPI](https://spec.openapis.org/oas/v3.0.1.html)
for the Headless Heimdall APIs.
This document provides the OAS3OpenAPI specificationdescription 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 OpenID Connect (OIDC) and the FAPI 2.0 Security Profile and without having to gain a
thorough understanding of the constraints placed by FAPI.
The interface consists of end-pointsthree operations, which are called when -User Theauthentication __Headlessis 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`initiated and after it is completed.
> Please note that where an operation name is used it references the `operationId` value for a given endpoint and HTTP method
Initiating Authorization is supported by the `getAuth` operation:
- The `getAuth` operation (`get /auth`) should be called by the financial institution at the
financial institution to notify Heimdallbeginning thatof an interactionauthorization hascode completed successfullygrant. This is typically immediately after -it Thereceives __Failure End-point__ `POST /auth/:interactionId/doFail` should be called by the financial institutionan authorization
request from a TPP.
toCompleting Authorization notifyis Heimdallsupported thatby the interaction has`doConfirm` failed.and `doFail` operations:
#### Changes in- Release 2024.34.1
* Refactored Security Scheme Objects to use common definitions across all API Hub APIsThe `doConfirm` operation (`post /auth/{interactionId}/doConfirm`) should be called by the financial institution to notify Heimdall that an interaction has completed successfully.
- The `doFail` operation * Implemented the correct Security Requirements for this API description, reflecting security patterns available in API Hub
version:(`post /auth/{interactionId}/doFail`) operation should be called by the financial institution to notify Heimdall that the interaction has failed.
#### Changes in Version 2024.3437.10
tags: - name: headless-heimdall * security:Refactored `post` operations to -use a {}Path parameter
- OzoneConnectJwtAuth: [] paths:* Refined descriptions /auth:to add clarity for readers
get:
* Added tags:`client_id` and `request_uri` query parameters to `getAuth` operation
- headless-heimdall #### Changes in summary: Start an authorisation interaction
description: |
The Headless Authorization End-point should be called by the financial institution at the beginning of the
interaction.
The end-point validates all the parameters that are passed to it to ensures that the
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 outcomesVersion 2024.34.1
* Refactored Security Scheme Objects to use common definitions across all API Hub APIs
* Implemented the correct Security Requirements for this API description, reflecting security patterns available in API Hub
version: 2024.37.0
tags:
- name: Initiate Authorization
description: Operations that support initiating the authorization of a User
- name: Complete Authorization
description: Operations that support completing the authorization of a User,
indicating either success or failure
security:
- {}
- OzoneConnectJwtAuth: []
paths:
/auth:
get:
tags:
- __Success__: The end-point returns a status 200. The body contains a JSON object with theInitiate Authorization
summary: Initiate an authorisation interaction
operationId: getAuth
interaction and all the querydescription: parameters|
extracted from the OIDC request object. The `getAuth` operation should be called by - __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.the financial institution at the beginning of the
interaction. The operation validates all the parameters that are passed to it to ensure that the
authorization request is FAPI compliant and has only the client_id` and `redirect_uri` parameters.
The operation responds with one of the three outcomes:
- __Success__: The operation returns a status 200. The body contains a JSON object with the
interaction and ###all Processingthe aquery successparameters responseextracted from the OIDC request object.
There are three key fields in the success response that financial institutions are likely to be interested in:
- __Non-redirectable failure__: This indicates a failure where validation of the OIDC Client
- `interactionfailed.interactionId`: ThisThe isfinancial theinstitution interactionshould identifierrender thatan shoulderror bepage usedand withend the interaction.
subsequent calls to Headless- Heimdall when this authorization request is completed by__Redirectable failure__: This indicates a failure where the financialOIDC institution.client has been validated
- `interaction.params.claims.id_token.openbanking_intent_id`: If thisbut interactionvalidation isof forthe aparameters UKof OBIEthe consentAuthorization Request failed. The operation therefore
authorisation, the Consent Id is contained inresponds thiswith field.a The 303 redirect, which the financial institution canmust use to redirect the Ozone Consent Manager API User **without modification**.
### Processing a success response
There are two toproperties retrievein the consentsuccess response that financial institutions are likely to be interested - `tpp.directoryRecord`: Where Ozone is integrated with a Directory Service, this contains a record
in:
- `interaction.interactionId`: The interaction identifier that should be used with
subsequent calls to Headless Heimdall when this authorization request is completed by the financial institution.
- `tpp.directoryRecord`: Where Ozone is integrated with a Directory Service, this contains a record
of the TPP record as held on the directory. The structure of the record will depend on the directory. Directory record as held by Ozone in base 64 encoded format.
### Parameters
When calling this API, the financial institution must pass on **all the query parameters or hash parameters** received from the TPP
in the authorization request. The FAPI 2.0 Security Profile states that a Client will **_only_** send the `client_id` and `request_uri` values, as
specified by the [Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-5.3.3.2-2.6). However, Heimdall is
the authoritative source for making that decision, hence all query parameters must be passed on. No query parameters are therefore
defined here as a result.
responses:
of the TPP record"200":
as held on the directory. The structure of the record willdescription: depend|
on the directory. Directory record as held by Ozone in base 64 encodedThis format.indicates that the parameters were successfully validated.
### Parameters The OAS3financial doesinstitution notshould havecontinue awith waythe tonext indicatestages aof flexiblethe setinteraction, ofusing querythe parameters.`interactionId`
When calling this API,as the financialunique institutionidentifier shouldwith passwhich onto alltrack the queryinteraction parameterswith orthe hashUser
parameters
received from the TPP content:
in the authorization request. operationIdapplication/json:
headlessAuthorization responses: schema:
"200": description$ref: |'#/components/schemas/AuthSuccessResponse'
"303":
This indicates that the parameters were successfully validated.description: |
TheThis financialindicates institutionthat shouldthe continueparameters withwere thenot nextsuccessfully stagesverified.
of
the interaction, keeping track of the However, there were no indications that returnedthe interactionId.request originated from an invalid client.
content: The financial institution should respond to application/json:the customer with a redirect to the URI returned by the API
schema: (including the query or hash parameters included in $ref: '#/components/schemas/AuthSuccessResponse'the URL)
"303400":
description: |
This indicates that the parameters were not successfully verified.
However,Heimdall therecould werenot noverify indications that the request originated from ana invalidvalid client.
The financial institution should render respondan toerror thepage customerand with a__must not__ redirect back to the URITPP.
returned by
the API (including the query or hash parameters included in the URL)
"400"content:
description: | application/json:
This indicates that theschema:
parameters were not successfully verified. $ref: Heimdall could not verify that the request originated from a valid client.'#/components/schemas/AuthErrorResponse'
/auth/{interactionId}/doConfirm:
post:
operationId: doConfirm
tags:
The financial institution should render an error page.- Complete Authorization
summary: End an authorisation interaction Thewith financiala institutionsuccess __must not__ redirect back to the TPP.
response
description: |
content:The `doConfirm` operation should be called by the financial institution once the
application/json: user interaction has been completed and the schema:resource owner has authorized
access. This operation updates $ref: '#/components/schemas/AuthErrorResponse'
/auth/:interactionId/doConfirm:the interaction state and generates an OIDC
post: Authorization Code operationId:value doConfirm- `code` - and the rest of tags:the response that should be
- headless-heimdall returned to the summary:TPP.
Ends
an authorisation interaction with a success response When supported by Security Profile the description:financial |institution can specify the
The Confirmation End-point should beset calledof byclaims theto financialbe institutionadded onceto the userID interactionToken. Heimdall creates an ID Token with
has been completed and the resource owner has authorized access. these claims along with any claims required by FAPI Theand doConfirmOIDC. callPlease updatesnote thethat interaction
state generates an OIDC `code` and the rest ofunder the FAPI 2.0 Security Profile ID Tokens are not responsesupported thatin shouldthe befront returned
to the TPP. channel, and therefore will Thenot financialbe institutionreturned can specifyto the setClient ofas claimsthe toresult beof addedan to
the id_token. Heimdall creates an interaction. Please refer to the id_token with these claims along with any claims required by FAPI and OIDC[Security Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#table-1)
for more details.
Heimdall returns a 303 with a redirect uri. This resource owner should be
redirected to this URI.
### Parameters
The request body can contain an arbitrary set of request body can contain an arbitrary set of
`application/x-www-form-urlencoded` name-value pairs. These are added by
These are added by Heimdall to the id_tokenID Token. The claim name is set to the parameter name and the
and the claim value to the parameter value.
Claim names prefixed by `heimdall.` act as control parameters for the tokens that
are produced. that are produced. These claims are not added to the id_tokenID Token.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
"heimdall.suppressRefreshToken":
description: Where supported, allows a financial institution to send parameters
type: boolean that control the lifetime of Access Tokens and availability of
description: | Refresh Tokens. These features are not supported for the UAE
Suppresses the generation of a refresh token. Open Finance Framework. Financial institutions can, however, add claims that will
If set to true, a refresh token is not generated. be included in an ID Token, which can be requested by a TPP dependent on the OAuth
If set to false, a refresh token is generated only if Heimdall has been scope granted by the User.
configured totype: supportobject
the refresh_token grant type. additionalProperties: true
parameters:
If not specified, Heimdall treats this as false.- $ref: '#/components/parameters/InteractionId'
responses:
"303":
Note that this feature *must not* be used fordescription: CBUAE|
A redirect URI that "heimdall.accessTokenValidity":
contains an authorization code along with additional
type:parameters integeras required by OIDC.
If an description:internal |error occurs during processing of the request an `error` and
Specifies (in no`error_description` ofparameters seconds)will howbe longreturned.
the generated access token should be valid for.
The redirect URI must Ifbe notreturned specified,to the systemUser defaultto isredirect used.them back to the TPP.
/auth/{interactionId}/doFail:
post:
operationId: doFail
Note that this feature *must not* betags:
used for CBUAE - Complete Authorization
summary: End "heimdall.refreshTokenValidity":
an authorisation interaction with a failure response
description: |
type: integer The `doFail` operation should be called by the financial institution once the
description: | User interaction has been completed and has resulted in a failure to grant
Specifies (in number of seconds) howaccess longto the generatedTPP. refreshExamples tokenfailure scenarios include:
* The User does not authenticate successfully.
should be valid for. * The User declines the authorisation of consent.
The If`doFail` notoperation specified,updates the systeminteraction defaultstate, isgenerates used.an OIDC `error`
and returns the rest of the response that should be Notereturned thatto thisthe feature *must not* be used for CBUAETPP.
The financial institution can specify the `error` and `error_description` as
additionalProperties: true x-www-form-urlencoded parameters:. If `error` and `error_description` omitted
- $ref: '#/components/parameters/interactionId' then default values will be returned responses:in the redirect URI.
"303": Heimdall returns a 303 with a redirect description:URI, |which should be sent to the
Heimdall returnsUser ato redirect them urito thatthe containsTPP.
an
authorization code along with requestBody:
content:
additional parameters as required by OIDC. application/x-www-form-urlencoded:
In case an internal errorschema:
occurred while processing the request, heimdall returns type: object
an error parameter. properties:
In both cases, the financial institution must redirect the resource owner to theerror:
redirect uri. /auth/:interactionId/doFail: post: operationIdtype: doFailstring
tags: - headless-heimdall description: |
summary: Ends an authorisation interaction with a failure response description: |An OAuth2.0 or OIDC error
The failure End-point should be called by the financial institution once the user interactionerror_description:
has been completed and has resulted in a failure to gaintype: access.string
parameters:
(e.g. when the user declines to authorise, does not- provide the appropriate credentials etc.)$ref: '#/components/parameters/InteractionId'
responses:
The doFail call updates the"303":
interaction state, generates an OIDC `error` and the rest of thedescription: |
response that should be returned toA theredirect TPP.URI that contains the parameters required to indicate the error Theto financial
institution can specify the `error` and `error_description` as x-www-form-urlencoded parameters. the TPP.
Heimdall returns a 303 with a
redirect uri. This resource owner should be redirected to this URI. If an internal error occurs during requestBody:processing of the request an `error` and
content: application/x-www-form-urlencoded:
`error_description` parameters will be returned.
schema:
type: object The redirect URI must be returned to the User to redirect them back to properties:the TPP.
components:
schemas:
InteractionId:
errordescription: Unique identifier for the interaction with the User
type: string
AuthSuccessResponse:
type: object
descriptionproperties:
| interaction:
description: The Anproperties OAuth2.0of ora OIDCsuccessfully errorinitiated interaction
type: object
error_description: properties:
typeinteractionId:
string parameters: - $ref: '#/components/parametersschemas/interactionId'
responses:
"303":InteractionId'
descriptionparams:
| Heimdall returnsdescription: aQuery redirectparameters uriunbundled thatfrom containsthe anoriginal authorization coderequest, alongincluding with
additional parameters as required byquery OIDC.parameters, hash parameters, and properties of the JWT-Secured
In case an internal error occurred while processing the request, heimdall returnsAuthorization Request (JAR) sent in the Pushed Authorization Request.
an error parameter. In both cases, the financial institution must redirect the resource owner to the redirect uri.
componentstype: object
properties:
schemas: AuthSuccessResponse: type: object client_id:
properties: interaction: description: The `client_id` value that the caller type:claims objectto have. At this stage,
properties: interactionId: Heimdall has verified that the `client_id` exists.
type: string type: string
description: An identifier for this interaction response_type:
params: description: |The request grant type. This will default to `code`` for the CBUAE release
Query parameters unbunbled from the original authorization request. as per the constraints of the FAPI 2.0 ThisSecurity includesProfile
both query parameters and hash parameters. type: string
This also includes parameters extracted from the OIDC request object. enum:
type: object - code
properties: scope:
client_id: type: string
description: | request:
The clientId that the caller claims to have. type: string
At this stage,scopes:
Heimdall has verified that the client id exists. description: The requested scopes in the Authorization Request
type: string response_type: array
type items:
string scopetype: string
claims:
type: string requestdescription: The requested claims in the Authorization Request.
type: string type: object
scopes: additionalProperties: true
description: | additionalProperties: true
claims:
The requested scope in the authorization request broken down into an array type: object
status:
type: array type: string
items: consentId:
type: string
description: An identifier for consent
claims: deprecated: true
description: | consentIdsList:
The requestedtype: claimsarray
in the authorization request. description: |
type: object Consent Ids associated with the interaction.
additionalProperties: true Note that RAR requests additionalProperties:may truecontain multiple consents. However, support for this is not required in the CBUAE claims:2024 standards and LFIs may consider
type: object that this array may have a single status:value.
typeitems:
string consentId: type: string
tpp:
type: string $ref: "#/components/schemas/tpp"
descriptionAuthErrorResponse:
An identifier for consent description: Provides details of the authorization error. Includes OAuth 2.0
deprecated: true error properties
consentIdsListtype: object
required:
type: array - interactionId
- error
description: | - error_description
properties:
Consent Ids associated with the interaction.noRedirect:
description: An indicator that defines whether Notethe thatEnd RARUser requestsshould maybe containredirected multipleback consents.to However,the support
for this is not required in the CBUAE 2024 standards and LFIs mayClient considerdue to the error. Please note that relates to an earlier release and Heimdall and
that this array may have a single value. is therefore deprecated for the CBUAE implementation.
items: type: boolean
typedeprecated: stringtrue
tpperror:
$refdescription: "#/components/schemas/tpp"
AuthErrorResponse:The error code as defined by [RFC
type: object 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
properties: noRedirecttype: string
error_description:
type: boolean errordescription: The error description as defined by [RFC
type: string error_description:6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: string
interactionId:
type$ref: string'#/components/schemas/InteractionId'
tpp:
type: object
description: |
The TPP record as held by Ozone.
If Ozone 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.
required:
- clientId
- orgId
- softwareStatementId
- tppName
properties:
clientId:
type: string
description: The client clientIdidentifier for the TPP as issued by the OzoneTrust Framework
orgId:
type: string
description: The organization ididentifier for the TPP
softwareStatementId:
type: string
description: The organizationsoftware statement ididentifier for the TPPClient
tppName:
type: string
description: The name of the TPP
directoryRecord:
type: string
description: The latest copy of the TPP directory record if the TPP has TPP has
registered with a directory
parameters:
interactionIdInteractionId:
name: interactionId
indescription: queryUnique identifier for the interaction with the schema:User
typein: stringpath
required: true
descriptionschema:
Identifier for the interaction $ref: '#/components/schemas/InteractionId'
securitySchemes:
OzoneConnectJwtAuth:
description: |
Communications between the API Hub and the LFI Ozone Connect implementation are
secured using the "JWT Auth" mechanism, where the Client presents a signed JSON Web
Token as a credential. Web Token as a credential.
The Server MUST verify the signature in order to authenticate the Client.
Please note that the value of the `scheme` parameter is not a registered HTTP
Authentication Scheme, to indicate it is specific to Ozone Connect. Please
refer to API Hub documentation for further details.
type: http
scheme: Ozone-Connect-JWT-Auth
|