openapi: 3.0.0
info:
  description: |
    This is the specification of the bLink 'consent-flow' module API.
  version: 2.0.15.0-fi
  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-2/consent-flow/v2
tags:
  - name: oauth
    description: |
      **oauth**
      OAuth endpoint
paths:
  /oauth/token:
    post:
      tags:
        - oauth
      summary: Get the OAuth access and refresh token
      description: >
        Returns the OAuth access and refresh token for the specified client and
        target.

        Providers can deploy this endpoint under a separate base path (e.g.,
        without a version number). SIX forwards the requests accordingly.
      operationId: oauthToken
      parameters:
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - client_id
                - grant_type
                - username
              properties:
                grant_type:
                  type: string
                  description: either authorization_code or refresh_token
                  enum:
                    - authorization_code
                    - refresh_token
                code:
                  type: string
                  description: authorization code if applicable
                refresh_token:
                  type: string
                  description: refresh token if applicable
                redirect_uri:
                  type: string
                  description: original redirect uri if applicable
                client_id:
                  type: string
                  description: client id
                username:
                  type: string
                  maxLength: 64
                  description: username of the resource owner
      responses:
        '200':
          description: OAuth token response
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauthTokenResponse'
        '400':
          $ref: '#/components/responses/oauthError400'
        '401':
          $ref: '#/components/responses/oauthError401'
        '403':
          $ref: '#/components/responses/oauthError403'
        '406':
          $ref: '#/components/responses/oauthError406'
        '415':
          $ref: '#/components/responses/oauthError415'
        '500':
          $ref: '#/components/responses/oauthError500'
        '502':
          $ref: '#/components/responses/oauthError502'
        '504':
          $ref: '#/components/responses/oauthError504'
  /oauth/revoke:
    post:
      tags:
        - oauth
      summary: Revoke an OAuth token (access or refresh)
      description: >
        - Revokes the specified OAuth token (must be done separately for access
        token and refresh token)

        - Providers must validate that the revocation is initiated by the
        legitimate client 

        - Providers can deploy this endpoint under a separate base path (e.g.,
        without a version number). SIX forwards the requests accordingly.
      operationId: oauthRevoke
      parameters:
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - token
              properties:
                token:
                  type: string
                  description: token to be revoked
                token_type_hint:
                  type: string
                  description: either access_token or refresh_token
                  enum:
                    - access_token
                    - refresh_token
      responses:
        '200':
          description: OAuth token revocation success
          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/oauthError400'
        '401':
          $ref: '#/components/responses/oauthError401'
        '403':
          $ref: '#/components/responses/oauthError403'
        '406':
          $ref: '#/components/responses/oauthError406'
        '415':
          $ref: '#/components/responses/oauthError415'
        '500':
          $ref: '#/components/responses/oauthError500'
        '502':
          $ref: '#/components/responses/oauthError502'
        '504':
          $ref: '#/components/responses/oauthError504'
  /oauth/username:
    post:
      tags:
        - oauth
      summary: Validate the username of the resouce owner
      description: |
        Returns whether or not a username could have been validated.
      operationId: oauthUsername
      parameters:
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - username
              properties:
                username:
                  type: string
                  maxLength: 64
                  description: username of the resource owner
      responses:
        '200':
          description: OAuth username response
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Pragma:
              $ref: '#/components/headers/Pragma'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauthUsernameResponse'
        '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'
components:
  parameters:
    clientid_in_header:
      name: X-CorAPI-Client-ID
      in: header
      description: 'ID of the client forwarded to the provider. (SCOPE: FI)'
      required: true
      schema:
        type: string
    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_targetid_in_header:
      name: X-CorAPI-Target-ID
      in: header
      description: 'ID of the target, e.g., a financial institution. (SCOPE: FI - optional)'
      required: false
      schema:
        type: string
    optional_psu_ip_in_header:
      name: X-PSU-IP-Address
      in: header
      description: 'IP address of the user initiating the operation (SCOPE: FI - optional)'
      required: false
      schema:
        type: string
    optional_psu_user_agent_in_header:
      name: X-PSU-User-Agent
      in: header
      description: 'User of the client software (SCOPE: FI - optional)'
      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
    WWW-Authenticate:
      description: i.e. "Bearer error='invalid_token'" according to RFC6750 section-3
      schema:
        type: string
  schemas:
    oauthTokenResponse:
      title: oAuth Token Response
      required:
        - access_token
        - token_type
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          default: bearer
        expires_in:
          minimum: 1
          type: integer
        refresh_token:
          type: string
        scope:
          type: string
          maxLength: 256
    oauthUsernameResponse:
      title: oAuth Username Response
      required:
        - valid_username
      type: object
      properties:
        valid_username:
          type: boolean
          example: true
    oauthErrorResponse:
      title: >-
        OAuth 2.0 Error Response for the Token Endpoint and Username Validation
        Endpoint
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            Error codes for oauthErrorResponse. For further details see the
            "Error Handling" section of the "Consent Management 2.0"
            documentation and the section 5.2 of the OAuth 2.0 Specification
            (RFC6749).
          example: invalid_request
        error_description:
          type: string
          description: >-
            Human-readable ASCII [USASCII] text providing additional
            information, used to assist the client developer in understanding
            the error that occurred.
          example: Invalid authorization code
        error_uri:
          type: string
          description: >-
            A URI identifying a human-readable web page with information about
            the error, used to provide the client developer with additional
            information about the error.
    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-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      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'
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      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'
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      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'
      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'
      description: Internal Server Error
      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'
      description: Service Unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
    oauthError400:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Bad Request - The format of the request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
    oauthError401:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Unauthorized - Client authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
    oauthError403:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Forbidden - Access to endpoint denied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
    oauthError406:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Not Acceptable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
    oauthError415:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Unsupported Media Type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
    oauthError500:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
    oauthError502:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Bad Gateway
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
    oauthError504:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: >-
        Gateway Timeout - The service provider did not answer in the required
        time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/oauthErrorResponse'
