openapi: 3.0.0
info:
  description: |
    This is the specification of the bLink 'platform' module API.
  version: 3.0.0.5-six_caas
  title: bLink API - platform module
  contact:
    name: SIX BBS AG
    url: https://www.six-group.com/en/products-services/banking-services/blink.html
servers:
  - url: https://api.six-group.com/api/bankingservices/b-link/platform/v3
tags:
  - name: directory
    description: |
      **participant information**
      Information about participating parties.
  - name: diagnostics
  - name: routinginstructions
paths:
  /directory/clients:
    get:
      tags:
        - directory
      summary: Retrieve a list of all registered clients (e.g., third party providers)
      description: >
        Returns a list of clients with information regarding software and
        supported use cases.
      operationId: retrieveClients
      parameters:
        - $ref: '#/components/parameters/query_participant_status'
        - $ref: '#/components/parameters/query_embed_asset_type'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of clients
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pagedDirectoryClientItems'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
  /directory/clients/{clientId}:
    get:
      tags:
        - directory
      summary: >-
        Retrieve the information for a registered client (e.g. third party
        provider)
      description: >
        Returns information regarding software and supported use cases of a
        client.
      operationId: retrieveClientDetail
      parameters:
        - $ref: '#/components/parameters/path_clientId'
        - $ref: '#/components/parameters/query_embed_asset_type'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '200':
          description: Information for a client
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directoryClientItem'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
  /directory/providers:
    get:
      tags:
        - directory
      summary: >-
        Retrieve a list of all registered providers (e.g., financial
        institutions)
      description: >
        Returns a list of providers with information regarding software and
        supported use cases.
      operationId: retrieveProviders
      parameters:
        - $ref: '#/components/parameters/query_participant_status'
        - $ref: '#/components/parameters/query_embed_asset_type'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of providers
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pagedDirectoryProviderItems'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
  /directory/providers/{providerId}:
    get:
      tags:
        - directory
      summary: >-
        Retrieve the information for a registered provider (e.g., financial
        institutions)
      description: >
        Returns information regarding software and supported use cases of a
        provider.
      operationId: retrieveProviderDetail
      parameters:
        - $ref: '#/components/parameters/path_providerId'
        - $ref: '#/components/parameters/query_embed_asset_type'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '200':
          description: Information for a provider
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directoryProviderItem'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
  /healthcheck:
    get:
      tags:
        - diagnostics
      summary: health status of the API
      description: Endpoint to check the health status of the API for GET method.
      operationId: healthCheckGet
      parameters:
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/optional_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '200':
          description: Health Check Response
          headers:
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthCheckResponse'
    post:
      tags:
        - diagnostics
      summary: health status of the API
      description: Endpoint to check the health status of the API for POST method.
      operationId: healthCheckPost
      parameters:
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/optional_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: Health Check Response
          headers:
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthCheckResponse'
  /routinginstructions:
    get:
      tags:
        - routinginstructions
      summary: instructed routes per communication
      description: >-
        Returns instructed routes for service user to service provider
        communication
      operationId: routingInstructions
      parameters:
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/optional_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '200':
          description: Routing Instruction Response
          headers:
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/routingInstructionResponse'
components:
  parameters:
    path_clientId:
      name: clientId
      in: path
      description: id of the client
      required: true
      schema:
        maxLength: 30
        type: string
    path_providerId:
      name: providerId
      in: path
      description: id of the provider
      required: true
      schema:
        maxLength: 30
        type: string
    query_participant_status:
      name: status
      in: query
      description: |
        Returns clients or providers with the corresponding status.
      schema:
        $ref: '#/components/schemas/directoryParticipantStatus'
    query_embed_asset_type:
      name: embed_assets
      in: query
      description: |
        - ALL  = Embed both logos and icons as base64
        - LOGO = Embed only logos as base64 (no icons)
        - ICON = Embed only icons as base64 (no logos)
        - NONE = No embedded assets
      schema:
        $ref: '#/components/schemas/directoryEmbedAssetType'
    offset:
      name: offset
      in: query
      description: The number of items to skip before starting to collect the result set.
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    limit:
      name: limit
      in: query
      description: The number of items to return.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    correlation_in_header:
      name: X-Correlation-ID
      in: header
      description: >-
        Unique ID (defined by the caller) which will be reflected back in the
        response.
      required: true
      schema:
        type: string
        maxLength: 64
    agent_in_header:
      name: User-Agent
      in: header
      description: Name and version of the of the Client software
      required: true
      schema:
        type: string
    optional_agent_in_header:
      name: User-Agent
      in: header
      description: Name and version of the of the client software
      required: false
      schema:
        type: string
    optional_instance_id_in_header:
      name: X-Instance-ID
      in: header
      description: >-
        (Deprecated) Identifies an on-prem application instance which uses a
        legacy on-prem certificate in the mTLS connection. Do not use the header
        otherwise.
      required: false
      schema:
        type: string
        maxLength: 64
  headers:
    Content-Language:
      description: always en
      schema:
        type: string
    Content-Type:
      description: application/problem+json; charset=utf-8 according to RFC7807
      schema:
        type: string
    X-Correlation-ID:
      description: >-
        Client defined ID from request to correlate HTTP requests between a
        client and a server
      schema:
        type: string
        maxLength: 64
        example: f058ebd6-02f7-4d3f-942e-904344e8cde5
    X-CorAPI-Source:
      description: |
        The header value is always PLATFORM
      schema:
        type: string
        enum:
          - PLATFORM
          - PROVIDER
  responses:
    standard400:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-CorAPI-Source:
          $ref: '#/components/headers/X-CorAPI-Source'
      description: Bad Request - The format of the request was invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard401:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-CorAPI-Source:
          $ref: '#/components/headers/X-CorAPI-Source'
      description: >-
        Unauthorized - Either no token or an invalid (e.g., token expired) token
        was received.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard403:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-CorAPI-Source:
          $ref: '#/components/headers/X-CorAPI-Source'
      description: >-
        Forbidden - A valid OAuth Token was received, but access was denied.
        (Depending on the security requirements, providers can return 404
        instead)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard404:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-CorAPI-Source:
          $ref: '#/components/headers/X-CorAPI-Source'
      description: >-
        Not Found - Either the endpoint does not exist or a requested resource
        is not yet available (e.g., account statements)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard500:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-CorAPI-Source:
          $ref: '#/components/headers/X-CorAPI-Source'
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard501:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-CorAPI-Source:
          $ref: '#/components/headers/X-CorAPI-Source'
      description: Not Implemented
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    standard503:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-CorAPI-Source:
          $ref: '#/components/headers/X-CorAPI-Source'
      description: Service Unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
  schemas:
    pagedDirectoryClientItems:
      title: Paged Directory Client Items
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/directoryClientItem'
        pagination:
          $ref: '#/components/schemas/pagination'
    directoryClientItem:
      title: Directory Client Item
      allOf:
        - required:
            - clientId
          type: object
          properties:
            clientId:
              type: string
              example: CIDX1234567890
        - $ref: '#/components/schemas/directoryParticipantItem'
    pagedDirectoryProviderItems:
      title: Paged Directory Provider Items
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/directoryProviderItem'
        pagination:
          $ref: '#/components/schemas/pagination'
    directoryProviderItem:
      title: Directory Provider Item
      allOf:
        - required:
            - providerId
          type: object
          properties:
            providerId:
              type: string
              example: IIDX1234567890
        - $ref: '#/components/schemas/directoryParticipantItem'
    directoryParticipantItem:
      title: Directory Participant Item
      required:
        - status
        - companyName
        - companyNameAbbreviation
        - companyUrl
        - productName
        - productInfoUrl
        - contact
        - registrationDate
        - lastModified
      type: object
      properties:
        status:
          $ref: '#/components/schemas/directoryParticipantStatus'
        companyName:
          maxLength: 50
          type: string
          example: ACME
        companyNameAbbreviation:
          maxLength: 50
          type: string
          description: Abbreviation of company name for mobile applications
          example: ACME
        companyUrl:
          type: string
          example: https://www.acme.com
        productName:
          maxLength: 50
          type: string
          description: Product name of client
          example: ACME accounting software
        productInfoUrl:
          type: string
          example: https://acme.com/amce_accounting
          description: Product Url of client
        contact:
          type: array
          example:
            - type: BUSINESS
              designation: Account and Payments Services
              emailAddress: business-contact@acme.com
            - type: TECHNICAL
              emailAddress: technical-contact@acme.com
              phone: +41 58 999 9999
            - type: SUPPORT
              emailAddress: support-contact@acme.com
              phone: +41 58 999 9997
          items:
            $ref: '#/components/schemas/directoryContact'
        logo:
          $ref: '#/components/schemas/directoryImage'
        icon:
          $ref: '#/components/schemas/directoryImage'
        registrationDate:
          type: string
          format: date
          example: '2018-04-13'
        lastModified:
          type: string
          format: date-time
          example: '2018-04-13T11:11:11Z'
        useCases:
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/directoryUseCaseItem'
        consentFlows:
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/directoryConsentFlowItem'
        features:
          type: object
          additionalProperties:
            type: string
    directoryContact:
      title: Directory Contact
      required:
        - emailAddress
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - BUSINESS
            - TECHNICAL
            - SUPPORT
        designation:
          maxLength: 80
          type: string
        emailAddress:
          maxLength: 80
          type: string
          format: email
        phone:
          maxLength: 20
          type: string
    directoryUseCaseItem:
      title: Directory Use Case Information
      required:
        - from
        - name
        - status
        - version
      type: object
      properties:
        name:
          type: string
          example: ais
        version:
          type: string
          example: v3
        status:
          type: string
          example: CERTIFIED
          enum:
            - ONBOARDING_CERTIFICATION
            - CERTIFIED
        from:
          type: string
          format: date-time
          example: '2018-04-13T11:11:11Z'
        until:
          type: string
          format: date-time
          example: '2018-04-13T11:11:11Z'
        scopes:
          type: string
          example: urn:blink:ow:ordrplc urn:blink:ow:ordrplc:write
        properties:
          type: object
          additionalProperties:
            type: string
    directoryConsentFlowItem:
      title: Directory Consent Flow Information
      required:
        - type
        - version
        - status
        - from
        - until
        - endpointInfos
      type: object
      properties:
        type:
          type: string
          example: consent-flow-v2
        version:
          type: string
          example: v2
        status:
          type: string
          example: CERTIFIED
          enum:
            - ONBOARDING_CERTIFICATION
            - CERTIFIED
        from:
          type: string
          format: date-time
        until:
          type: string
          format: date-time
          example: '2018-04-13T11:11:11Z'
        endpointInfos:
          type: array
          items:
            $ref: '#/components/schemas/directoryEndpointInfo'
    directoryParticipantStatus:
      title: Directory Participant Status
      type: string
      example: ACTIVE
      default: ACTIVE
      enum:
        - ACTIVE
        - INACTIVE
        - SUSPENDED
        - ONBOARDING_DEVELOPMENT
    directoryEmbedAssetType:
      title: Embed Asset Type
      type: string
      example: ALL
      default: ALL
      enum:
        - ALL
        - ICON
        - LOGO
        - NONE
    directoryImage:
      title: Directory Image
      type: string
      pattern: ^data:image/svg\+xml;base64,[A-Za-z0-9+/]+=*$
      format: base64
      example: >-
        data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj4KICA8Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgc3R5bGU9ImZpbGw6cmVkOyIgLz4KPC9zdmc+Cg==
    directoryEndpointInfo:
      title: Information for Endpoint
      type: object
      properties:
        name:
          type: string
          example: clientConsentBackendUrl
        url:
          type: string
          example: https://www.acme.com/consents/v2
    pagination:
      type: object
      properties:
        totalCount:
          type: integer
          description: >
            Total number of records, useful for pagination: use offset and limit
            parameters to query for any given page.

            As long as the offset is less than totalCount, there will be records
            in the response. Once offset is larger

            than totalCount, the response will be empty.
          example: 100
        offset:
          type: integer
          description: >-
            the offset which was requested in the query, or the default used by
            the server.
          example: 0
        limit:
          type: integer
          description: >-
            the limit which was requested in the query, or the default used by
            the server.
          example: 20
    commonErrorResponse:
      title: Common Error Response
      type: object
      properties:
        type:
          $ref: '#/components/schemas/commonErrorType'
        title:
          type: string
          example: This is the general problem description
        detail:
          type: string
          example: >-
            Detailed problem description with respect to the current request,
            e.g., invalid account number format
        instance:
          type: string
          example: path/to/corresponding/resource
    commonErrorType:
      title: Common Error Type
      type: string
      description: >-
        Error Types for commonErrorResponse. See Appendix for detailed
        information.
      example: /problems/TECHNICAL_ERROR
      enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
    healthCheckResponse:
      title: Health Check Response
      type: object
      properties:
        requestDateTime:
          title: Request Time
          type: string
          format: date-time
          example: '2018-04-13T11:11:11Z'
        receivedHeaders:
          title: Received Headers
          type: array
          items:
            type: object
            properties:
              headerName:
                type: string
                example: X-Correlation-ID
              headerValue:
                type: string
                description: As received
        receivedPayload:
          title: Received Payload
          type: string
          example: ... as received ...
    routingInstructionResponse:
      title: Routing Instruction Response
      required:
        - requestDateTime
        - message
        - instructedRoutingTargets
      type: object
      properties:
        requestDateTime:
          title: Request Time
          type: string
          format: date-time
          example: '2018-04-13T11:11:11Z'
        message:
          title: Routing instruction message
          type: string
        instructedRoutingTargets:
          title: List of existing instructed routing targets
          type: array
          items:
            type: string
