openapi: 3.0.1
info:
  title: Message Service API
  description: "\t\t<h1>What are messages and how do they work?</h1>\n\t\t<p>\n\t\t
    Messages are notifications that are sent to alert other listening components about
    actions performed on the platform.\n\t\tFor example, several components might
    be interested to be notified when a new document has been uploaded in the UI:
    reconciliation, signing, accounting software etc.\n\t\t</p>\n\t\t<p>\n\t\tTo be
    able to receive these messages, you need to <a href=\"https://docs.btx.banqup.com/docs/extensions/plugin/plugin-api\"\
    >register an extension</a> with the Message Listeners extension point,\n\t\tusing
    the Register an extension endpoint.\n\t\tBecause not all components will be interested
    in all messages, this API allows you to filter exactly what messages you want
    to receive,\n\t\tusing different message categories and types.\n\t\t</p>\n\t\t
    <h2>Access limitations</h2>\n\t\t<p>\n\t\tKeep in mind that certain access limitations
    exist that control sending/receiving messages,\n\t\tso users might need certain
    permissions to send/listen to messages belonging to a specific category/type or
    to register an extension.\n\t\t</p>\n\t\t<h1>Authorization callbacks</h1>\n\t\t
    <p>\n\t\tWhen a user attempts to register a listener for a specific category of
    messages (e.g. documents),\n\t\tthe Message Service will perform a callback to
    a messageAuthorizer that verifies if the user has permission\n\t\tto listen to
    document-related messages.\n\t\t</p>\n\t\t<p>\n\t\t<b>Example:</b> A user registers
    a message listener within the Plugin Service.\n\t\tAt this point, the Plugin Service
    will call the Message Service to check if the user is authorized to register\n
    \t\tthe listener and check the category filter of the message (e.g., documents),
    specified by the user in the initial registration request.\n\t\tThen, the Message
    Service calls the messageAuthorizer to check if the listener has permissions to
    receive messages belonging to that category.\n\t\t</p>\n\t\t<p>\n\t\tAdditionally,
    it is possible for the messageAuthorizer to respond with additional information
    regarding message filters,\n\t\twhich is added to the authorizationInfo and returned
    to the Plugin Service to be stored with the extension.\n\t\tThis can help the
    Message Service decide later on if a message that is produced should be sent to
    this listener or not.\n\t\t</p>\n"
  version: 2.0.0
servers:
- description: The Message Service API REST endpoint via localtest.me
  url: https://api.btx.fr.banqup.com/core/message
- description: The Message Service API REST endpoint via localtest.me
  url: https://api.btx.eu.banqup.com/core/message
paths:
  /v2/messages:send:
    post:
      tags:
      - message-service
      summary: Sends a message
      description: 'Sends a message to all listeners that are authorized to receive
        it. <br/> Scope: []'
      operationId: sendMessageV2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
        required: true
      responses:
        '202':
          description: The message has been accepted and will soon be broadcast to
            all subscribed message listeners.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '403':
          description: You must have the permission 'message_category_send' on the
            category that is in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
      x-action:
        value: send
  /v2/messageAuthorizers/subject:getAuthorizer:
    post:
      tags:
      - message-service
      summary: Gets subject message authorization filter
      description: 'Convenience endpoint that returns a subject filter. <br/> Scope:
        []'
      operationId: getSubjectMessageAuthorizer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMessageAuthorizerRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageAuthorizerResponse'
      x-action:
        value: getAuthorizer
  /v2/messageAuthorizers/permission:getAuthorizer:
    post:
      tags:
      - message-service
      summary: Get permission message authorization filter
      description: 'Convenience endpoint that returns a user/permission filter. <br/>
        Scope: []'
      operationId: getPermissionMessageAuthorizer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMessageAuthorizerRequest'
        required: true
      responses:
        '200':
          description: 'The default permission filter to determine whether or not
            a subject may receive events that are broadcast by the message service.
            The returned filter checks the scope and resource mentioned in the message
            against the subject of the receiver (for example: you need space_read
            to receive document events about documents in that space)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageAuthorizerResponse'
      x-action:
        value: getAuthorizer
  /v1/messages:
    post:
      tags:
      - message-service
      summary: '[DEPRECATED] Sends a message'
      description: Sends a message to all listeners that are authorized to receive
        it. **Deprecated** due to API rework. Use /v2/messages:send instead.
      operationId: sendMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
        required: true
      responses:
        '202':
          description: The message has been accepted and will soon be broadcast to
            all subscribed message listeners.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '403':
          description: You must have the permission 'message_category_send' on the
            category that is in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
      deprecated: true
  /v1/messageAuthorizers/subject/authorizeMessage:
    post:
      tags:
      - message-service
      summary: '[DEPRECATED] Get subject message authorization filter'
      description: Convenience endpoint that returns a subject filter. **Deprecated**
        due to rename. Use /v2/messageAuthorizers/subject:getAuthorizer instead.
      operationId: getDefaultSubjectFilter
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionFilterRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionFilterResponse'
      deprecated: true
  /v1/messageAuthorizers/permission/authorizeMessage:
    post:
      tags:
      - message-service
      summary: '[DEPRECATED] Get permission message authorization filter'
      description: Convenience endpoint that returns a user/permission filter. **Deprecated**
        due to rename. Use /v2/messageAuthorizers/permission:getAuthorizer instead.
      operationId: getDefaultPermissionFilter
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionFilterRequest'
        required: true
      responses:
        '200':
          description: 'The default permission filter to determine whether or not
            a subject may receive events that are broadcast by the message service.
            The returned filter checks the scope and resource mentioned in the message
            against the subject of the receiver (for example: you need space_read
            to receive document events about documents in that space)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionFilterResponse'
      deprecated: true
components:
  schemas:
    JsonNode:
      type: object
    SendMessageRequest:
      required:
      - category
      type: object
      properties:
        resourceId:
          maxLength: 256
          minLength: 0
          type: string
        scope:
          maxLength: 256
          minLength: 0
          type: string
        category:
          maxLength: 1024
          minLength: 0
          type: string
        channel:
          maxLength: 256
          minLength: 0
          type: string
        type:
          maxLength: 64
          minLength: 0
          type: string
        audience:
          maxLength: 256
          minLength: 0
          type: string
        subject:
          maxLength: 256
          minLength: 0
          type: string
        orderGroup:
          maxLength: 256
          minLength: 0
          pattern: .*\S.*
          type: string
        data:
          $ref: '#/components/schemas/JsonNode'
    MessageResponse:
      required:
      - messageId
      type: object
      properties:
        messageId:
          type: string
    GetMessageAuthorizerRequest:
      required:
      - subject
      type: object
      properties:
        subject:
          maxLength: 256
          minLength: 0
          type: string
        extensionData:
          type: object
    GetMessageAuthorizerResponse:
      type: object
      properties:
        permissionFilterList:
          type: array
          items:
            $ref: '#/components/schemas/PermissionFilter'
    PermissionFilter:
      type: object
      properties:
        type:
          maxLength: 64
          minLength: 0
          type: string
        subject:
          maxLength: 256
          minLength: 0
          type: string
    MessageRequest:
      required:
      - category
      type: object
      properties:
        resourceId:
          maxLength: 256
          minLength: 0
          type: string
        scope:
          maxLength: 256
          minLength: 0
          type: string
        category:
          maxLength: 1024
          minLength: 0
          type: string
        channel:
          maxLength: 256
          minLength: 0
          type: string
        type:
          maxLength: 64
          minLength: 0
          type: string
        audience:
          maxLength: 256
          minLength: 0
          type: string
        subject:
          maxLength: 256
          minLength: 0
          type: string
        orderGroup:
          maxLength: 256
          minLength: 0
          pattern: .*\S.*
          type: string
        data:
          $ref: '#/components/schemas/JsonNode'
    PermissionFilterRequest:
      required:
      - subject
      type: object
      properties:
        subject:
          maxLength: 256
          minLength: 0
          type: string
        extensionData:
          type: object
    PermissionFilterResponse:
      type: object
      properties:
        permissionFilterList:
          type: array
          items:
            $ref: '#/components/schemas/PermissionFilter'
  securitySchemes:
    message:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.btx.fr.banqup.com/v1/oauth20/authorization
          tokenUrl: https://api.btx.fr.banqup.com/v1/oauth20/token_kc
          scopes: {}