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.

  version: Release 2024.34

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 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
        authorisation, the Consent Id is contained in this field. The financial institution 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. 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 institution 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 financial institution should continue with the next stages of the interaction, keeping track of the
            returned interactionId.

          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSuccessResponse'

        "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 institution should respond to the customer with a redirect to the URI returned by the API
            (including the query or hash parameters included in the URL)

        "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 institution should render an error page.

            The financial institution __must not__ redirect back to the TPP.

          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'

      security:
        - bearerAuth: []

  /auth/:interactionId/doConfirm:
    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 financial 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 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 303 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 this as false.

                    Note that this feature *must not* be used for CBUAE

                "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:
        "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 financial institution 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 financial 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 financial institution can specify the `error` and `error_description` as x-www-form-urlencoded parameters.

        Heimdall returns a 303 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: |
                    An OAuth2.0 or OIDC error

                error_description:
                  type: string

      parameters:
        - $ref: '#/components/parameters/interactionId'

      responses:
        "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 financial institution must redirect the resource owner to the redirect uri.

      security:
        - bearerAuth: []

components:
  schemas:
    AuthSuccessResponse:
      type: object
      properties:
        interaction:
          type: object
          properties:
            interactionId:
              type: string
              description: An identifier for this interaction
            params:
              description: |
                Query parameters unbunbled from the original authorization request.

                This includes both query parameters and hash parameters.

                This also includes parameters extracted from the OIDC request object.
              type: object
              properties:
                client_id:
                  description: |
                    The clientId that the caller claims to have.

                    At this stage, Heimdall has verified that the client id exists.
                  type: string
                response_type:
                  type: string
                scope:
                  type: string
                request:
                  type: string
                scopes:
                  description: |
                    The requested scope in the authorization request broken down into an array
                  type: array
                  items:
                    type: string
                claims:
                  description: |
                    The requested claims in the authorization request.
                  type: object
                  additionalProperties: true
              additionalProperties: true
            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:
      type: object
      properties:
        noRedirect:
          type: boolean
        error:
          type: string
        error_description:
          type: string
        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 encoded format.

      required:
        - clientId
        - orgId
        - softwareStatementId
        - tppName

      properties:
        clientId:
          type: string
          description: The clientId for the TPP as issued by Ozone

        orgId:
          type: string
          description: The organization id for the TPP

        softwareStatementId:
          type: string
          description: The organization id for the TPP

        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 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