openapi: 3.0.0
info:
  description: |
    This is the specification of the bLink 'consent-flow' module API.
  version: 2.0.15.1-six_caas
  title: bLink API - consent flow module
  contact:
    name: SIX BBS AG
    url: https://www.six-group.com/en/products-services/banking-services/blink.html
servers:
  - url: https://api-cert.six-group.com/api/bankingservices/b-link/consent-flow/v2
tags:
  - name: permissions
    description: |
      **permissions**
      CaaS Permissions Endpoints
paths:
  /permissions/{providerId}/{userId}:
    post:
      tags:
        - permissions
      description: Create a permission
      operationId: createPermission
      parameters:
        - $ref: '#/components/parameters/path_providerId'
        - $ref: '#/components/parameters/path_userId'
        - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/psu_ip_in_header'
        - $ref: '#/components/parameters/psu_user_agent_in_header'
      requestBody:
        required: true
        description: >-
          When connecting a user, a permission needs to be created for accounts
          access. The user will be redirected to their chosen provider and will
          perform SCA - upon successful SCA with the provider, the permission
          will move to an authorized status. This call returns the details of
          the permission, including the URL where the user will be redirected
          for permission authorization. These are details of the implementation
          but concerning the SCA, each provider needs to be thoroughly tested by
          the consumer.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/permissionCreationRequest'
      responses:
        '201':
          description: Permission created.
          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/permissionCreationResponse'
        '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'
    get:
      tags:
        - permissions
      description: Retrieve a list of permissions of a given provider and user ID
      operationId: retrievePermissions
      parameters:
        - $ref: '#/components/parameters/path_providerId'
        - $ref: '#/components/parameters/path_userId'
        - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/psu_ip_in_header'
        - $ref: '#/components/parameters/psu_user_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '200':
          description: Retrieve a permission for a given provider and user ID
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/permissionItem'
        '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'
  /permissions/{providerId}/{userId}/{permissionId}:
    get:
      tags:
        - permissions
      description: Retrieve a permission for a given provider, user ID and permission ID
      operationId: retrievePermission
      parameters:
        - $ref: '#/components/parameters/path_providerId'
        - $ref: '#/components/parameters/path_userId'
        - $ref: '#/components/parameters/path_permissionId'
        - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/psu_ip_in_header'
        - $ref: '#/components/parameters/psu_user_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '200':
          description: >-
            Retrieve a permission for a given provider, user ID and permission
            ID
          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/permissionItem'
        '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'
    delete:
      tags:
        - permissions
      description: Revoke a permission for a given provider, user ID and permission ID
      operationId: deletePermission
      parameters:
        - $ref: '#/components/parameters/path_providerId'
        - $ref: '#/components/parameters/path_userId'
        - $ref: '#/components/parameters/path_permissionId'
        - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/psu_ip_in_header'
        - $ref: '#/components/parameters/psu_user_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '204':
          description: Permission ID revoked successfully
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
        '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'
  /permissions/{providerId}/{userId}/{permissionId}/refresh:
    post:
      tags:
        - permissions
      description: >-
        trigger token-refresh inside the permission for a given provider, user
        ID and permission ID
      operationId: refreshPermission
      parameters:
        - $ref: '#/components/parameters/path_providerId'
        - $ref: '#/components/parameters/path_userId'
        - $ref: '#/components/parameters/path_permissionId'
        - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/psu_ip_in_header'
        - $ref: '#/components/parameters/psu_user_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '204':
          description: >-
            Refresh the provider-token for a permission for a given provider,
            user ID and permission ID
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Pragma:
              $ref: '#/components/headers/Pragma'
        '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'
        '503':
          $ref: '#/components/responses/standard503'
components:
  parameters:
    path_providerId:
      name: providerId
      in: path
      description: id of the provider
      required: true
      schema:
        maxLength: 30
        type: string
    targetid_in_header:
      name: X-CorAPI-Target-ID
      in: header
      description: >-
        ID that identifies the provider (e.g., a financial institution). (SCOPE:
        SIX required)
      required: true
      schema:
        type: string
    psu_ip_in_header:
      name: X-PSU-IP-Address
      in: header
      description: >-
        IP address of the user initiating the operation or AUTO for system
        triggered processes (SCOPE: SIX required)
      required: true
      schema:
        type: string
    psu_user_agent_in_header:
      name: X-PSU-User-Agent
      in: header
      description: >-
        User agent of the user initiating the operation or AUTO for system
        triggered processes (SCOPE: SIX required)
      required: true
      schema:
        type: string
    path_permissionId:
      name: permissionId
      in: path
      description: permission ID
      required: true
      schema:
        type: string
        format: uuid
    path_userId:
      name: userId
      in: path
      description: >
        <p> The Service User can choose the User-ID value freely. It is allowed
        to assign multiple User-ID values to the same Customer.   The only
        requirement is that each User-ID can be traced back to the correct
        end-user unambiguously. <p> For a specific User-ID value and Provider ID
        combination, there can only be one valid Permission at a time. As soon
        as a new permission  is initiated using the same User-ID and Provider
        ID, the bLink CaaS Service will revoke any previously valid permission
        of the  same User-ID and Provider ID. <p> Please note: Even when using
        different User-IDs to create multiple valid permissions, it could still
        happen that the Service Provider doesn't allow multiple valid Access
        Tokens in parallel for the same E-Banking Access,  which will result in
        previous permissions being invalidated as soon as they are used in an
        API-call.
      required: true
      schema:
        type: string
        pattern: ^([a-zA-Z0-9\-.]{1,250})$
    authorization_in_header:
      name: Authorization
      in: header
      description: Bearer followed by a base64 encoded OAuth access token
      required: true
      schema:
        type: string
    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_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. (SCOPE: SIX_CAAS - optional, SIX_CAAS_INTERNAL - optional).
      required: false
      schema:
        type: string
        maxLength: 64
    optional_authorization_in_header:
      name: Authorization
      in: header
      description: Bearer followed by a base64 encoded OAuth access token
      required: false
      schema:
        type: string
  headers:
    Cache-Control:
      description: 'must include: no-store'
      schema:
        type: string
        default: no-store
    Content-Language:
      description: always en
      schema:
        type: string
    Content-Type:
      description: application/problem+json; charset=utf-8 according to RFC7807
      schema:
        type: string
    Pragma:
      description: 'must be: no-cache'
      schema:
        type: string
        default: no-cache
    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: >
        Indicates whether the response was created by the bLink platform or by
        the provider.
      schema:
        type: string
        enum:
          - PLATFORM
          - PROVIDER
  schemas:
    permissionCreationRequest:
      title: Permission Creation Request
      type: object
      required:
        - username
        - scope
      properties:
        username:
          type: string
          maxLength: 64
          example: username
        csrf:
          type: string
          example: '1234567890'
          description: this property is deprecated and no longer serves any purpose.
        externalReference:
          type: string
          pattern: ^([a-zA-Z0-9 /\-?:().,']{1,500})$
          maxLength: 36
          example: 93398946-b5a4-484c-b759-75eb22d0f40d
          description: >-
            An optional reference to identify the permission. This reference
            will be returned in the callback url after the authorization of the
            permission.
        instanceId:
          type: string
          pattern: ^([a-zA-Z0-9\-.]{1,64})$
          description: Application instance id
          example: a3cfe345-3106-4548-b1c5-60e1bf263df3
        scope:
          type: string
          maxLength: 256
          description: >-
            OAuth2 scope to be added to the authorizationUrl. Multiple scopes
            are space-delimited
          example: urn:blink:abc:srv
        callback:
          type: string
          maxLength: 256
          description: >-
            The callback URL to which the resource owner is redirected after the
            permission creation request is completed. The URL must be registered
            with bLink. If the callback property is not specified, then the
            default callback URL is used.
          example: https://third-party-provider-example.com/callback
    permissionCreationResponse:
      title: Permission Creation Response
      type: object
      required:
        - providerId
        - permissionId
        - authorizationUri
        - status
      properties:
        providerId:
          type: string
          example: '1234'
        username:
          type: string
          maxLength: 64
          example: username
        permissionId:
          type: string
          format: uuid
          example: c46d7cb8-500d-48ba-a085-671173a84cd3
        authorizationUri:
          type: string
          example: >-
            http://provider-example.com/authorize?redirect_uri=http%3A%2F%localhost&state=1234
        status:
          $ref: '#/components/schemas/permissionStatus'
        externalReference:
          type: string
          pattern: ^([a-zA-Z0-9 /\-?:().,']{1,500})$
          example: 93398946-b5a4-484c-b759-75eb22d0f40d
        instanceId:
          type: string
          pattern: ^([a-zA-Z0-9\-.]{1,64})$
          description: Application instance id
          example: a3cfe345-3106-4548-b1c5-60e1bf263df3
    permissionItem:
      title: Permission Item
      type: object
      required:
        - providerId
        - permissionId
        - status
      properties:
        providerId:
          type: string
          example: '1234'
        username:
          type: string
          maxLength: 64
          example: hans.muster@six-group.com
        permissionId:
          type: string
          format: uuid
          example: c46d7cb8-500d-48ba-a085-671173a84cd3
        status:
          $ref: '#/components/schemas/permissionStatus'
        externalReference:
          type: string
          pattern: ^([a-zA-Z0-9 /\-?:().,']{1,500})$
          example: 93398946-b5a4-484c-b759-75eb22d0f40d
        instanceId:
          type: string
          pattern: ^([a-zA-Z0-9\-.]{1,64})$
          description: Application instance id
          example: a3cfe345-3106-4548-b1c5-60e1bf263df3
        scope:
          type: string
          maxLength: 256
          description: OAuth2 scope to be added to the authorizationUrl
          example: urn:blink:abc:srv
    permissionStatus:
      title: Permission status
      type: string
      enum:
        - received
        - valid
        - revoked
        - expired
        - revoked_by_psu
      example: received
    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
  responses:
    standard400:
      headers:
        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-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-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-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-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'
    standard503:
      headers:
        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'
