openapi: 3.0.1
servers:
- url: https://{server}/v2024.07<your-ozone-hh-server>
info:
descriptiontitle: Headless Heimdall APIs
variablescontact:
servername: Ozone Financial Technology Limited
defaultdescription: hh.*|
This document provides description:the TheOAS3 serverspecification thatfor the APIAPIs provided isby hostedHeadless onHeimdall.
info: title: Headless HeimdallThese APIs are implemented description:by |Ozone and should be called This document providesby the financial institution at the OAS3end of specificationtheir forauthorization thejourneys.
APIs
provided by Headless Heimdall. The interface allows for an financial institution to develop Thesethe APIsuser areinterface implementedfor bycustomers Ozonewithout
and should be called byhaving theto ASPSPdeal atwith the endcomplexities of theirOIDC authorizationand journeys.FAPI and without having to gain Headlessa
Heimdall provides an API interfacethorough tounderstanding an OIDC Authorization Serverof the constraints placed by FAPI.
The interface allows for an ASPSP to develop the user interface for PSUs without__Version 2.2 Release 2024.31__
The interface consists of end-points
having- toThe deal__Headless with the complexities of OIDC and FAPI and without having to gain aAuthorization End-point__ `GET /auth` should be called by the financial institution at the
begining thorough understanding of the constraints placed by FAPI.
of an authorization code grant. This is typically immediately after it receives an authorization
The interfacerequest consistsfrom of end-points:a TPP
- The __HeadlessConfirmation Authorization End-point__ `GET`POST /auth`/auth/:interactionId/doConfirm` should be called by the
ASPSP at the financial institution to notify beginingHeimdall ofthat an authorizationinteraction has codecompleted grantsuccessfully.
This
is typically immediately after it- receivesThe an authorization
request from a TPP
- The __Confirmation __Failure End-point__ `POST /auth/:interactionId/doConfirm`doFail` should be called by the financial institution
ASPSP to notify Heimdall that anthe interaction has completed successfully.
failed.
#### Coming soon
- The __Failure End-point__ `POST /auth/:interactionId/doFail` should be called by the ASPSP following changes can be expected in the next release:
- some enumeration and object definitions remain to be aligned with CBUAE specifications. These will be updated
- tospecific notifychanges Heimdallexpected thatin the interaction has failed.
next release have been marked as ***TODO*** in the document
version: Version 2.2 Release 262024.4
31
tags:
- name: headless-heimdall
paths:
/auth:
get:
tags:
- headless-heimdall
summary: Start an authorisation interaction
description: |
The Headless Authorization End-point should be called by the financial ASPSPinstitution 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 an identifier for 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 ASPSPinstitution 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 302303 redirect. The financial ASPSPinstitution 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 ASPSPsfinancial 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 ASPSPfinancial institution.
- `interaction.params.claims.id_token.openbanking_intent_id`: If this interaction is for a UK OBIE consent
authorisation, the Consent Id is contained in this field. The financial ASPSPinstitution can use the Ozone Consent Manager API
to retrieve the consent
- `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 the record will depend on the directory. Directory record as held by Ozone in base 64 encoded format.
### Parameters
OAS3 does not have a way to indicate a flexible set of query parameters.
When calling this API, the financial ASPSPinstitution should pass on all the query parameters or hash parameters received from the TPP
in the authorization request.
operationId: headlessAuthorization
responses:
"200":
description: |
This indicates that the parameters were successfully validated.
The ASPSPfinancial institution should continue with the next stages of the interaction, keeping track of the
returned interactionId.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthSuccessResponse'
302"303":
description: |
This indicates that the parameters were not successfully verified.
However, there were no indications that the request originated from an invalid client.
The financial ASPSPinstitution should respond to the PSUcustomer with a redirect to the URI returned by the API
(including the query or hash parameters included in the URL)
400"400":
description: |
This indicates that the parameters were not successfully verified.
Heimdall could not verify that the request originated from a valid client.
The financial ASPSPinstitution should render an error page.
The The ASPSPfinancial institution __must not__ redirect back to the TPP.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthErrorResponse'
security:
- bearerAuth: []
/auth/:interactionId/doConfirm:/doConfirm:
post:
post operationId: doConfirm
tags:
- headless-heimdall
summary: Ends an authorisation interaction with a success response
description: |
The Confirmation End-point should be called by the ASPSPfinancial institution once the user interaction
has been completed and the resource owner has authorized access.
The doConfirm call updates the interaction state generates an OIDC `code` and the rest of the
response that should be returned to the TPP.
The The ASPSP financial institution can specify the set of claims to be added to the id_token. Heimdall creates an
id_token with these claims along with any claims required by FAPI and OIDC.
Heimdall returns a 302303 with a redirect uri. This resource owner should be redirected to this URI.
### Parameters
The request body can contain an arbitrary set of `application/x-www-form-urlencoded` name-value pairs.
These are added by Heimdall to the id_token. The claim name is set to the parameter name
and the claim value to the parameter value.
Claim names prefixed by `heimdall.` act as control parameters for the tokens that are produced.
These claims are not added to the id_token.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
"heimdall.suppressRefreshToken":
type: boolean
description: |
Suppresses the generation of a refresh token.
If set to true, a refresh token is not generated.
If set to false, a refresh token is generated only if Heimdall has been
configured to support the refresh_token grant type.
If not specified, Heimdall treats configuredthis toas supportfalse.
the
refresh_token grant type. Note that this feature If*must not* specified,be Heimdallused treatsfor this asCBUAE
false.
"heimdall.accessTokenValidity":
type: integer
description: |
Specifies (in no of seconds) how long the generated access token should be valid for.
If not specified, the system default is used.
Note that this feature *must not* be used for CBUAE
"heimdall.refreshTokenValidity":
type: integer
description: |
Specifies (in number of seconds) how long the generated refresh token
should be valid for.
If not specified, the system default is used.
Note that this feature *must not* be used for CBUAE
additionalProperties: true
parameters:
- $ref: '#/components/parameters/interactionId'
responses:
302"303":
description: |
Heimdall returns a redirect uri that contains an authorization code along with
additional parameters as required by OIDC.
In case an internal error occurred while processing the request, heimdall returns
an error parameter.
In both cases, the UIfinancial Providerinstitution must redirect the resource owner to the redirect uri.
security:
- bearerAuth: []
/auth/:interactionId/doFail:
post:
operationId: doFail
tags:
- headless-heimdall
summary: Ends an authorisation interaction with a failure response
description: |
The failure End-point should be called by the ASPSPfinancial institution once the user interaction
has been completed and has resulted in a failure to gain access.
(e.g. when the user declines to authorise, does not provide the appropriate credentials etc.)
The doFail call updates the interaction state, generates an OIDC `error` and the rest of the
response that should be returned to the TPP.
the TPP.
The financial ASPSPinstitution can specify the `error` and `error_description` as x-www-form-urlencoded parameters.
Heimdall returns a 302303 with a redirect uri. This resource owner should be redirected to this URI.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
error:
type: string
description: |
properties: An OAuth2.0 or OIDC error:
type: stringerror_description:
descriptiontype: string
|
parameters:
- $ref: '#/components/parameters/interactionId'
An OAuth2.0 or OIDC error responses:
"303":
error_description: |
Heimdall returns a redirect uri type:that stringcontains an authorization code along with
parameters: - $ref: '#/components/parameters/interactionId'
additional parameters as required by OIDC.
responses: 302: In case an internal error occurred while processing the request, description:heimdall |returns
Heimdallan returnserror aparameter.
redirect
uri that contains an authorization code along with In both cases, the financial institution must redirect the additionalresource parametersowner asto requiredthe byredirect OIDCuri.
security:
In case an internal- errorbearerAuth: occurred[]
while
processingcomponents:
the request, heimdall returns schemas:
AuthSuccessResponse:
type: object
an error parameter. properties:
interaction:
In both cases, the UI Provider must redirect the resource ownertype: toobject
the redirect uri. securityproperties:
- bearerAuth: [] componentsinteractionId:
schemas: AuthSuccessResponse: type: objectstring
properties: description: An identifier for this interaction:
typeparams:
object properties: description: |
interactionId: Query parameters unbunbled from the original authorization type:request.
string
description: An identifierThis forincludes thisboth interactionquery parameters and hash parameters.
params: This also includes parameters extracted from description:the |OIDC request object.
Querytype: parametersobject
unbunbled from the original authorization request. properties:
This includes both query parameters and hash parameters. client_id:
This also includesdescription: parameters|
extracted from the OIDC request object. type:The objectclientId that the caller claims to have.
properties: At this stage, Heimdall client_id:has verified that the client id exists.
description: | type: string
The clientId thatresponse_type:
the caller claims to have. type: string
At this stage, Heimdall has verified that the client id exists.scope:
type: string
response_typerequest:
type: string
scope:scopes:
description: |
type: string The requested scope in the authorization request: broken down into an array
type: string type: array
scopes: items:
description: | type: string
The requested scope in the authorizationclaims:
request broken down into an array description: |
type: array The requested claims in items:the authorization request.
type: stringobject
claims: additionalProperties: true
descriptionadditionalProperties: |true
claims:
The requested claims in the authorization request. type: object
status:
If the authorization request is for the UK OBIE APIs, then the type: string
consentId:
property `id_token.openbanking_intent_id` indicates the consent to be authorised. type: string
typedescription: objectAn identifier for consent
deprecated: properties:true
consentIdsList:
id_token: type: array
typedescription: object|
Consent Ids associated with properties:
the interaction.
Note that RAR requests may contain openbanking_intent_id:
multiple consents. However, support for this is not required in the CBUAE 2024 standards and LFIs may consider
type: object that this array may have a single value.
propertiesitems:
type: string
tpp:
value: $ref: "#/components/schemas/tpp"
AuthErrorResponse:
type: object
typeproperties:
string noRedirect:
additionalProperties: true type: boolean
error:
claimstype: string
error_description:
type: object type: string
status: interactionId:
type: string
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 providesencoded format.
the
TPP's directory record as held by Ozone.required:
- clientId
properties: - orgId
clientId: - softwareStatementId
type:- stringtppName
properties:
orgId: clientId:
type: string
description: The softwareStatementId:clientId for the TPP as issued by Ozone
type: string orgId:
type: directoryRecord:string
description: The organization id type:for objectthe TPP
softwareStatementId:
additionalProperties: true AuthErrorResponsetype: string
type: object description: The organization properties:id for the TPP
noRedirect: tppName:
type: boolean type: string
error: description: The name of the type:TPP
string
error_descriptiondirectoryRecord:
type: string
interactionId:
type: string
description: The latest copy of the TPP directory record if the TPP has registered with a directory
parameters:
interactionId:
name: interactionId
in: query
schema:
type: string
required: true
description: Identifier for the interaction
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT | 