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 - 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 TPPwhen User authentication is 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 __Confirmation End-point__ `POST /auth/:interactionId/doConfirm``getAuth` operation (`get /auth`) should be called by the financial
financial institution toat notifythe Heimdallbeginning thatof an interactionauthorization hascode completed successfullygrant. This is typically
- The __Failure End-point__ `POST /auth/:interactionId/doFail` should be called by the financial institution
to notify Heimdall that the interaction has failed.
#### Changes in Release 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: Version 2024.34.1
tags:
- name: headless-heimdall
security:
- {}
- OzoneConnectJwtAuth: []
paths:
/auth:
get:
tags:
- headless-heimdall
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 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.
### Processing a success response
There are three key fields in the success response that financial institutions are likely to be interested in:
- `interaction.interactionId`: This is the interaction identifier that should be used with
subsequent calls to Headless Heimdall when this authorization request is completed by the financial institution.
- `interaction.params.claims.id_token.openbanking_intent_id`: If this interaction is for a UK OBIE consent immediately after it receives an authorization request from a TPP.
Completing Authorization is supported by the `doConfirm` and `doFail` operations:
- The `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 (`post /auth/{interactionId}/doFail`) operation should be
called by the financial institution to notify Heimdall that the interaction has
failed.
### Changes in Version 2024.46.0
* Added additional properties to the `tpp` data provided in the `get /auth` response
* Added details on content of `decodedSsa` property to provide guidance on
properties like `logo_uri` and `jwks_uri`
#### Changes in Version 2024.37.0
* Refactored `post` operations to use a Path parameter
* Refined descriptions to add clarity for readers
* Removed `additionalProperties: true` as not required and causes tooling issues
* Added `login_hint` to Authorization Request parameters
#### Changes in Version 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.46.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:
- Initiate Authorization
summary: Initiate an authorisation interaction
operationId: getAuth
description: |
The `getAuth` operation should be called by 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:
authorisation, the Consent Id is contained in this field- __Success__: The operation returns a status 200. The financialbody institutioncontains cana useJSON object with the
Ozone Consent Manager API interaction and all the to retrieve the consentquery parameters extracted from the OIDC request object.
- __Non- `tpp.directoryRecord`: Where Ozone is integrated with a Directory Service, this contains a recordredirectable failure__: This indicates a failure where validation of the OIDC Client
failed. The financial institution ofshould therender TPPan recorderror aspage heldand onend the directoryinteraction.
The
structure of the record will depend on the directory. Directory record as held by Ozone in base 64 encoded format.
- __Redirectable failure__: This indicates a failure where the OIDC client has been validated
### Parametersbut validation of the parameters of the Authorization Request OAS3failed. doesThe notoperation havetherefore a
way to indicate a flexible set of query parameters.responds with a 303 redirect, which the financial institution must Whenuse calling this API,to redirect the financialUser institution should pass on all the query parameters or hash parameters received from the TPP
**without modification**.
### Processing a success response
in the authorizationThere request.are two properties in the success response that operationId:financial headlessAuthorizationinstitutions are likely to be interested in:
responses: "200"- `interaction.interactionId`: The interaction identifier that should be used with
description: | subsequent calls to Headless Heimdall when this authorization request Thisis indicatescompleted thatby the parameters were successfully validatedfinancial institution.
- `tpp.directoryRecord`: Where Ozone Theis financial institution should continue integrated with thea nextDirectory stagesService, ofthis thecontains interaction,a keepingrecord
track of the of the TPP record as held on returnedthe interactionIddirectory. The structure of the record will depend on the directory. Directory content:record as held by Ozone in base 64 encoded format.
application/json: ### Parameters
schema: When calling this API, the financial institution must pass on **all the query parameters or $ref: '#/components/schemas/AuthSuccessResponse'
hash parameters** received from the TPP
"303": in the authorization request. The FAPI 2.0 Security description:Profile |states that a Client will This indicates that**_only_** send the parameters`client_id` wereand not successfully verified.`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, thereHeimdall wereis
no indications that the request originated from an invalidthe client.authoritative source for making that decision, hence all query parameters must be passed on. TheNo financialquery institutionparameters shouldare respondtherefore
to the customer with a redirect to the URIdefined returnedhere byas thea APIresult.
(including the query or hash parameters included in the URL)responses:
"400200":
description: |
This indicates that the parameters were not successfully verifiedvalidated.
The Heimdallfinancial couldinstitution notshould verifycontinue thatwith the requestnext originatedstages fromof athe validinteraction, client.using the `interactionId`
The financialas institutionthe shouldunique renderidentifier anwith errorwhich page.to track the interaction The financial institution __must not__ redirect back to the TPP.with the User
content:
application/json:
schema:
$ref: '#/components/schemas/AuthErrorResponseAuthSuccessResponse'
/auth/:interactionId/doConfirm: post"303":
operationId: doConfirm description: |
tags: - headless-heimdallThis indicates that the parameters were not summary:successfully Endsverified.
an
authorisation interaction with a success response However, description:there |were no indications that the request originated from an invalid Theclient.
Confirmation
End-point should be called by the financial institution once the user interaction The financial institution should respond to the customer haswith beena completedredirect andto the resourceURI ownerreturned hasby authorizedthe access.API
The doConfirm call updates(including the interactionquery stateor generateshash anparameters OIDCincluded `code` andin the restURL)
of
the "400":
response that should be returned to the TPP. description: |
The financial institution can specify the setThis ofindicates claimsthat tothe beparameters addedwere tonot thesuccessfully id_tokenverified.
Heimdall creates an id_token withHeimdall thesecould claimsnot alongverify withthat anythe claimsrequest requiredoriginated byfrom FAPIa andvalid OIDCclient.
Heimdall returns a 303 withThe afinancial redirectinstitution uri.should Thisrender resourcean ownererror shouldpage beand redirected to this URI.
__must not__ redirect back to the TPP.
### Parameters content:
The request body can contain an arbitrary set of `application/x-www-form-urlencoded` name-value pairs.application/json:
These are added byschema:
Heimdall to the id_token. The claim name is set to the parameter name $ref: '#/components/schemas/AuthErrorResponse'
and the claim value to the parameter value./auth/{interactionId}/doConfirm:
post:
operationId: doConfirm
Claim names prefixed bytags:
`heimdall.` act as control parameters for the tokens that- areComplete produced.Authorization
summary: End Thesean claimsauthorisation areinteraction notwith addeda tosuccess theresponse
id_token.
requestBodydescription: |
content: The `doConfirm` operation should be called by the financial application/x-www-form-urlencoded:
institution once the
user interaction schema:has been completed and the resource owner has authorized
type: object access. This operation updates the interaction state and generates an OIDC
properties: Authorization Code value - `code` - and the rest "heimdall.suppressRefreshToken":
of the response that should be
returned to the TPP.
type: boolean When supported by Security Profile the financial institution can specify the
description: | set of claims to be added to the ID Token. Heimdall creates an ID SuppressesToken thewith generation
of a refresh token. these claims along with any claims required by FAPI and OIDC. Please note that
If set to true, a refresh tokenunder isthe notFAPI generated2.0 Security Profile ID Tokens are not supported in the front
If set to falsechannel, aand refreshtherefore tokenwill isnot generatedbe onlyreturned ifto Heimdallthe hasClient beenas the result of an
interaction. configuredPlease refer to support the refresh_token grant type.
[Security Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#table-1)
for more details.
If not specified, Heimdall treatsreturns thisa as303 false.with a redirect uri. This resource owner should be
Note thatredirected to this featureURI.
*must
not* be used for CBUAE ### Parameters
The request "heimdall.accessTokenValidity":
body can contain an arbitrary set of
`application/x-www-form-urlencoded` name-value pairs. These type:are integeradded by
Heimdall to the ID Token. The claim name is description:set |to the parameter name and the
claim value to the parameter value.
Specifies
(in no of seconds) how long the generated access tokenClaim shouldnames beprefixed validby for`heimdall.` act as control parameters for the tokens
that are produced. These claims Ifare not added specified,to the system default is usedID Token.
requestBody:
content:
Note that this feature *must not* be used for CBUAE application/x-www-form-urlencoded:
schema:
"heimdall.refreshTokenValidity": description: Where supported, allows a financial institution to send parameters
type: integer that control the lifetime of description:Access |Tokens and availability of
Refresh SpecifiesTokens. (inThese numberfeatures ofare seconds)not howsupported longfor the generatedUAE
refresh token Open Finance Framework. Financial institutions can, shouldhowever, beadd validclaims for.that will
be included in an IfID not specifiedToken, thewhich systemcan defaultbe isrequested used.by a TPP dependent on the OAuth
Note thatscope thisgranted featureby *must not* be used for CBUAEthe User.
additionalPropertiestype: trueobject
parameters:
- $ref: '#/components/parameters/interactionIdInteractionId'
responses:
"303":
description: |
Heimdall returns aA redirect uriURI that contains an authorization code along with additional
additional parameters as required by OIDC.
InIf case an internal error occurredoccurs whileduring processing of the request, heimdallan returns`error` and
`error_description` parameters anwill errorbe parameterreturned.
In both cases, the financial institution mustThe redirect URI themust resourcebe ownerreturned to the User to redirect uri them back to the TPP.
/auth/:{interactionId}/doFail:
post:
operationId: doFail
tags:
- Complete headless-heimdallAuthorization
summary: EndsEnd an authorisation interaction with a failure response
description: |
The failure`doFail` End-pointoperation should be called by the financial institution once the
user interaction User interaction has been completed and has resulted in a failure to gaingrant access.
access (e.g. when to the userTPP. declines to authorise,Examples failure scenarios include:
* The User does not provide authenticate successfully.
* The User declines the appropriateauthorisation credentialsof etcconsent.)
The doFail`doFail` calloperation updates the interaction state, generates an OIDC `error` and
the rest of the and returns the rest of the response that should be returned to the TPP.
The financial institution can specify the `error` and `error_description` as
x-www-form-urlencoded parameters. If `error` and `error_description` omitted
Heimdall returns a 303 with a then default values will be returned in the redirect uri. This resource ownerURI.
Heimdall returns a 303 with a redirect URI, which should be redirected sent to the
User to redirect them to thisthe URITPP.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
error:
type: string
description: |
An OAuth2.0 or OIDC error
error_description:
type: string
parameters:
- $ref: '#/components/parameters/interactionIdInteractionId'
responses:
"303":
description: |
Heimdall returns aA redirect uriURI that contains anthe authorizationparameters coderequired alongto withindicate the error to
additional parameters as required bythe OIDCTPP.
In case If an internal error occurredoccurs whileduring processing of the request, heimdall returns an `error` and
an error parameter.`error_description` parameters will be returned.
In both cases, the financial institution mustThe redirect theURI must resourcebe ownerreturned to the User to redirect uri them back to the TPP.
components:
schemas:
AuthSuccessResponseInteractionId:
type: description: Unique identifier for the interaction with the User
type: string
AuthSuccessResponse:
type: object
properties:
interaction:
description: The properties of a successfully initiated interaction
type: object
properties:
interactionId:
type: string$ref: '#/components/schemas/InteractionId'
params:
description: An identifier for this interaction description: Query parameters unbundled from the original authorization request, including
query parameters, hash parameters, and properties of the JWT-Secured
Authorization Request (JAR) sent in the Pushed Authorization Request.
type: object
properties:
client_id:
description: The `client_id` value that the caller claims to have. At this stage,
Heimdall has verified that the `client_id` exists.
type: string
response_type:
description: The request grant type. This will default to `code` for the CBUAE release
as per the constraints of the FAPI 2.0 Security Profile
type: string
enum:
- code
scope:
type: string
request:
type: string
scopes:
description: The requested scopes in the Authorization Request
type: array
items:
type: string
claims:
description: The requested claims in the Authorization Request.
type: object
login_hint:
description: The value of the `login_hint` parameter sent in the Pushed Authorization
request. This value is expected to be encrypted as a JWE.
type: string
claims:
type: object
status:
type: string
consentId:
type: string
description: An identifier for consent
deprecated: true
consentIdsList:
type: array
description: |
Consent Ids associated with the interaction.
Note that RAR requests may contain multiple consents. However, support for this is not required in the CBUAE 2024 standards and LFIs may consider
that this array may have a single value.
items:
type: string
tpp:
$ref: "#/components/schemas/tpp"
AuthErrorResponse:
description: Provides details of the authorization error. Includes OAuth 2.0
error properties
type: object
required:
- interactionId
- error
- error_description
properties:
noRedirect:
description: An indicator that defines whether the End User should be redirected back to the
Client due to the error. Please note that relates to an earlier release and Heimdall and
is therefore deprecated for the CBUAE implementation.
type: boolean
deprecated: true
error:
description: The error code as defined by [RFC
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: string
error_description:
description: The error description as defined by [RFC
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: string
interactionId:
$ref: '#/components/schemas/InteractionId'
tpp:
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.
type: object
required:
- clientId
- orgId
- softwareStatementId
- tppId
- tppName
- decodedSsa
properties:
clientId:
description: The client identifier for the TPP as issued by the Trust Framework
type: string
pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
paramstppId:
description: |The identifier used by the API Hub to Query parameters unbunbled from the original authorization request.uniquely identify the TPP
type: string
This includes bothtppName:
query parameters and hash parameters. description: The TPP name recorded in the Trust ThisFramework
also includes parameters extracted from the OIDC request object. type: string
type: object obieTppId:
description: The UK properties:market TPP identifier. This property is not used for CBUAE and is therefore
client_id: marked as deprecated.
description: | type: string
deprecated: true
The clientId that thesoftwareStatementId:
caller claims to have. description: The software statement identifier for the Client.
At this stage, Heimdalltype: hasstring
verified that the client id exists. obieSoftwareStatementId:
description: The UK market software type:statement stringidentifier. This property is not used for CBUAE
response_type: and is therefore marked as deprecated.
type: string
deprecated: true
scope: obieSoftwareStatementName:
description: The UK market type: string
software statement name. This property is not used for CBUAE and
request: is therefore marked as deprecated.
type: string
deprecated: true
scopes: directoryRecord:
type: string
description: | description: The latest copy of the TPP directory record retrieve from the CBUAE Trust Framework The
requested scope in the authorization request broken down into an array directory, encoded as a Base 64 string
typeformat: arraybase64
ssa:
itemsdescription: The encoded Software Statement Assertion. This property is not used for CBUAE and is
type: string therefore marked as deprecated.
claimstype: string
deprecated: true
description decodedSsa:
| $ref: "#/components/schemas/softwareStatementProperties"
orgId:
The requested claims in the authorization request. description: The organization identifier for the TPP
type: string
object pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
additionalPropertiessoftwareStatementProperties:
true description: |
additionalProperties: true
The decoded software statement retrieved from the Trust Framework that provides
claims: the properties of the Client.
type: object
Please note:
status: - The JSON payload will type:contain stringother properties in addition to those listed
consentId: here. The properties listed here are considered most type:relevant stringfor activities
description:such Anas identifierTPP forlogo consentretrieval and JWS verification.
- deprecated:The truecontent reflects elements of discovery metadata, which in generally
consentIdsList: defined as a file rather than an type:API. arrayProviding constraints such as
description: |`minLength` and `maxLength` is impractical in this context
ConsentThe Idsfull associatedsoftware withstatement therecord interaction.is also available in the Trust Framework.
Please Notealso thatrefer RARthe requestsRegistration mayFramework containpage multiplein consents.the However,CBUAE supportstandards for
this is not required in the CBUAE 2024additional standardsguidance andon LFIsthese mayproperties.
consider type: object
properties:
that this array may have a single value.redirect_uris:
description: The redirect URIs registered items:by the TPP at the Trust Framework
type: array
string tppitems:
$reftype: "#/components/schemas/tpp"string
AuthErrorResponse: client_name:
type: object description: properties:Name of the Client to be presented to noRedirect:the End-User.
type: booleanstring
errorclient_uri:
typedescription: stringURL of the home page of error_description:the Client.
type: string
interactionIdlogo_uri:
typedescription: stringURL of the tpp:
Client logo.
type: object descriptiontype: |string
The TPP record as held by Ozone.jwks_uri:
description: URL of Ifthe OzoneClient TPPJSON ConnectWeb hasKey beenSet integrated into a directory,(JWKS) at the `directoryRecord`Trust providesFramework.
the TPP's directory record as held by Ozone in base 64type: encodedstring
format. requiredclient_id:
- clientIddescription: Unique Client Identifier.
- orgId type: string
- softwareStatementId roles:
- tppName description: The roles properties:under which the organization is registered at the Trust clientId:Framework.
type: stringarray
descriptionitems: The
clientId for the TPP as issued by Ozone type: string
orgId: sector_identifier_uri:
type: string description: URL using the https scheme description:to Thebe organizationused idin forcalculating thePseudonymous TPPIdentifiers
softwareStatementId: by the OP. Allows redirect URI values type:to stringbe grouped, easing registration
description: The organization id for themanagement.
TPP tppNametype: string
application_type: string
description: TheClient nameapplication oftype.
the TPP directoryRecordtype: string
organisation_id: type: string
description: Organization identifier Thefor latestorganization copythat ofowns the TPPClient.
directory record if the TPP has registered with atype: directorystring
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
| 