openapi: 3.0.1
info:
  title: trust_identity API
  description: Merged OpenAPI spec for trust_identity domain
  version: 1.0.0
servers:
- url: https://api.btx.fr.banqup.com/trust/identity
paths:
  /v1/registration/start:
    get:
      tags:
      - Registration
      summary: Get registration start form
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Retrieves the start form for the registration process based on country\
        \ and optional type/subbrand parameters.\n\nThis endpoint returns the appropriate\
        \ registration process definition, the associated start form and potentially\
        \ pre-populated variables.\n\n**User Account Type**: Can be accessed by Anonymous\
        \ Users.\n <br/> Scope: []"
      operationId: getRegistrationStartForm
      parameters:
      - name: country
        in: query
        description: Country code (e.g., BE, NL, FR)
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Registration type (company, individual, etc.)
        required: false
        schema:
          type: string
          default: ''
      - name: subbrand
        in: query
        description: Sub-brand identifier
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Registration start form retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartFormResponse'
              example:
                startForm:
                  id: form-12345
                  name: Registration Form
                  key: registrationForm
                  version: 1
                  fields:
                  - id: firstName
                    name: First Name
                    type: text
                    required: true
                  - id: lastName
                    name: Last Name
                    type: text
                    required: true
                  - id: email
                    name: Email
                    type: text
                    required: true
                startFormVariables:
                  ProcessName: documentOnboardingStart
                  brandText: Banqup
                  ui_locales: en
                  up_product: btxbe
                  theme: upg
                  brand: Banqup
                registrationEndpoint: /v1/registration
                processDefinitionId: PRC-47134568-ee0f-11ef-9e9a-4e00cc1acb07
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                error: Internal Server Error
                message: 'Failed to retrieve start form: Process key not found in
                  DMN response'
  /v1/registration:
    post:
      tags:
      - Registration
      summary: Start registration process
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Starts a registration process with the provided form values. This\
        \ endpoint:\n\n1. Creates a temporary user in the btx-tmp realm\n2. Starts\
        \ a process instance with the provided form values\n3. Returns a process instance\
        \ ID and authorization URL\n\nThe client should redirect the user to the authorization\
        \ URL to complete authentication.\nPKCE parameters (state, nonce, code_challenge)\
        \ are required for secure OAuth2 flow.\n\n**User Account Type**: Anonymous\
        \ User initiates the process. Upon completion, a Temporary User Account is\
        \ created.\n <br/> Scope: []"
      operationId: startRegistration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
            example:
              processDefinitionId: PRC-47134568-ee0f-11ef-9e9a-4e00cc1acb07
              values:
                ux:
                  country: BE
                  ProcessName: documentOnboardingStart
                  brandText: Banqup
                  ui_locales: en
                  up_product: btxbe
                  theme: upg
                  brand: Banqup
                ui_locales: en
                brand: Banqup
                layout: '001'
                email: user@example.com
                firstName: John
                lastName: Doe
              state: '9988223455'
              nonce: '123456'
              code_challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
              code_challenge_method: S256
        required: true
      responses:
        '200':
          description: 'Registration started successfully. Note that the API returns
            HTTP 200 even for validation

            errors, with the error information included in the response body.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RegistrationResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    processInstanceId: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f
                    status: started
                    authorizationUrl: https://iam.test.unifiedpost.com/auth/realms/test-btx-tmp/protocol/openid-connect/auth?client_id=btx-tmp-frontend&request_uri=urn:bqid:bwc4JK-ESC0w8acc191e-Y1LTC2
                error:
                  value:
                    status: 400
                    error: Validation Error
                    message: Email not found in validated request
  /v1/registrations:
    post:
      tags:
      - Registration
      summary: Start registration process and create static link
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Starts a registration process with the provided form values. This\
        \ endpoint:\n\n1. POST /v1/registrations → Starts processInstance → Returns\
        \ JSON with redirectUrl\n2. FE redirects user to /identity/v1/auth?processInstanceId=[id]\n\
        3. /v1/auth → Redirects user to Keycloak/BQID for enrollment\n4. User completes\
        \ enrollment (scans QR, verifies identity)\n5. /v1/auth/callback → Sets process\
        \ owner, collects tokens → Redirects to application\n6. Application receives\
        \ user at /idm/l2/process/[processInstanceId]\n <br/> Scope: []"
      operationId: createRegistration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewRegistrationRequest'
            examples:
              platformRegistration:
                summary: Platform registration
                value:
                  country: BE
                  email: user@example.com
                  firstName: John
                  lastName: Doe
              accountingRegistration:
                summary: Accounting registration
                value:
                  country: BE
                  email: user@example.com
                  firstName: John
                  lastName: Doe
                  type: accounting
                  spaceId: space-123
                  templateName: partner onboarding v1
                  region: EU
              upProductRegistration:
                summary: Registration with up_product
                value:
                  up_product: product-code-us
                  email: user@example.com
                  firstName: John
                  lastName: Doe
                  campaign: summer2024
                  sig: enrollment-abc123
        required: true
      responses:
        '200':
          description: 'Create registration and started successfully. Note that the
            API returns HTTP 200 even for validation

            errors, with the error information included in the response body.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RegistrationResponse'
                - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  value:
                    processInstanceId: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f
                    status: started
                    authorizationUrl: /identity/v1/auth?processInstanceId=PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f
                error:
                  value:
                    status: 400
                    error: Validation Error
                    message: country is required when up_product is not provided
  /v1/spaces/{spaceId}/users/invitations:
    post:
      tags:
      - Space User Invitations
      summary: Create a space user invitation
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Starts a new invitation process for a user to join a space.\n\nThe\
        \ invitation process is started via a BPMN message start event.\nThe spaceId\
        \ is set as the business key on the process instance for efficient querying.\n\
        The process instance name is set to `inviteNewSpaceUserStart-{inviteeEmail}-{spaceName}`.\n\
        \n**Authentication**: Requires a valid gateway token. Future: Keycloak UMA\
        \ permission check.\n <br/> Scope: []"
      operationId: createInvitation
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvitationRequest'
            example:
              event: inviteNewSpaceUserStart
              invitee:
                firstName: Minh Thu
                lastName: Phan
                email: thu.phan@unifiedpost.com
                permissions:
                  resources:
                  - id: 495b6aff-3e6c-4134-a042-ee4f6be45a06
                    name: The space
                    scopes:
                    - space_read
                    - space_write
                    uxHint: true
                    type: spaces:business
              space:
                id: 495b6aff-3e6c-4134-a042-ee4f6be45a06
                name: HELLO WORLD
                region: eu
                type: BUSINESS
                entity:
                  id: 123354-12A4-40a3-910c-7a8c06e32910
                  name: The Four Cubes NV
                  countryCode: BE
              inviter:
                firstName: Admin
                lastName: Space
                email: hello@unifiedpost.com
                subject: d8e8532a-fe97-4e17-b7c0-5706fd675055
      responses:
        '201':
          description: Invitation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationResponse'
              example:
                processInstanceId: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f
                status: started
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Space User Invitations
      summary: List space user invitations
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Lists all active invitation process instances for a given space.\n\
        \nQueries process instances by process definition key `inviteNewSpaceUserStart`\n\
        and business key matching the spaceId. Results include process variables.\n\
        \ <br/> Scope: []"
      operationId: listInvitations
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      responses:
        '200':
          description: List of invitations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationListResponse'
              example:
                invitations:
                - processInstanceId: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f
                  startTime: '2025-01-15T10:30:00Z'
                  processVariables:
                    event: inviteNewSpaceUserStart
                    invitee:
                      firstName: Minh Thu
                      lastName: Phan
                      email: thu.phan@unifiedpost.com
                total: 1
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Space User Invitations
      summary: Cancel invitation by email
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Cancels all active invitation process instances for a given email\
        \ address within a space.\n\nQueries process instances by business key (spaceId)\
        \ and filters by invitee email\nin the process variables. Returns 404 if no\
        \ matching invitation is found.\n <br/> Scope: []"
      operationId: cancelInvitationByEmail
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      - name: email
        in: query
        description: Email address of the invitee to cancel
        required: true
        schema:
          type: string
          format: email
      responses:
        '204':
          description: Invitation(s) cancelled successfully
        '404':
          description: No invitation found for the given email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                error: Not Found
                message: 'No invitation found for email: unknown@example.com in space:
                  495b6aff-3e6c-4134-a042-ee4f6be45a06'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/spaces/{spaceId}/users/invitation:remind:
    post:
      tags:
      - Space User Invitations
      summary: Send reminder for invitation
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Sends a reminder for all active invitation process instances matching\
        \ the given email address within a space.\n\nQueries process instances by\
        \ business key (spaceId) and filters by invitee email\nin the process variables.\
        \ For each matching invitation, increments the reminderCount\nvariable and\
        \ returns the updated count.\n\nReturns 404 if no matching invitation is found.\n\
        \ <br/> Scope: []"
      operationId: remindInvitation
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      - name: email
        in: query
        description: Email address of the invitee to remind
        required: true
        schema:
          type: string
          format: email
      responses:
        '200':
          description: Reminder(s) sent successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvitationReminderResponse'
              example:
              - processInstanceId: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f
                reminderCount: 1
        '404':
          description: No invitation found for the given email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                error: Not Found
                message: 'No invitation found for email: unknown@example.com in space:
                  495b6aff-3e6c-4134-a042-ee4f6be45a06'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/spaces/{spaceId}/users/invitations/{processInstanceId}:
    put:
      tags:
      - Space User Invitations
      summary: Update invitation invitee details
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Updates the firstName, lastName, and email of the invitee on an active\
        \ invitation process instance.\n <br/> Scope: []"
      operationId: updateInvitation
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      - $ref: '#/components/parameters/ProcessInstanceIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInvitationRequest'
            example:
              firstName: John
              lastName: Doe
              email: john.doe@example.com
      responses:
        '200':
          description: Invitation updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationResponse'
              example:
                processInstanceId: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f
                status: updated
        '404':
          description: Process instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                error: Not Found
                message: 'Process instance not found: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Space User Invitations
      summary: Cancel invitation by process instance ID
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Cancels an active invitation by deleting the process instance.\n <br/>\
        \ Scope: []"
      operationId: cancelInvitation
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      - $ref: '#/components/parameters/ProcessInstanceIdPath'
      responses:
        '204':
          description: Invitation cancelled successfully
        '404':
          description: Process instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                error: Not Found
                message: 'Process instance not found: PRC-9d8c21d6-1dc3-11f0-9476-ea93077f8d1f'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/spaces/{spaceId}/users/invitations:bulkImport:
    post:
      tags:
      - Space User Invitations
      summary: Bulk invite users via Excel upload
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Uploads an Excel (.xlsx) file containing multiple user invitations\
        \ and starts an invitation\nprocess for each valid row.\n\nThe file must match\
        \ the template available at\n`GET /v1/spaces/{spaceId}/users/invitations:bulkImport/template`.\n\
        Each row represents one invitee with a yes/no selection per role column.\n\
        \n**Role columns** (in order): `space_admin`, `purchases_full`, `purchases_limited`,\n\
        `sales_full`, `sales_limited`, `financial_full`, `accountant`.\n\n**Role normalisation\
        \ rules**:\n- If `purchases_full` is `yes`, `purchases_limited` is ignored\
        \ even if also `yes`.\n- If `sales_full` is `yes`, `sales_limited` is ignored\
        \ even if also `yes`.\n\nThe response is a JSON summary with the total number\
        \ of rows processed and a breakdown\nof successes and failures. A `200` does\
        \ not guarantee all rows succeeded — check\n`numberOfFailures` to determine\
        \ if any rows were rejected.\n\n**Constraints**:\n- Maximum file size: 5 MB\n\
        - Maximum data rows: 100\n- Accepted file type: `.xlsx` only\n\n**Authentication**:\
        \ Requires a valid Bearer token. Inviter details (name, email) are\nresolved\
        \ automatically from the JWT — they do not need to be provided in the file.\n\
        \ <br/> Scope: []"
      operationId: bulkImportInvitations
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The Excel (.xlsx) file containing invitation rows
      responses:
        '200':
          description: 'Bulk import processed. Returns a JSON summary of the import
            results. A 200 does not

            guarantee all rows succeeded — check `numberOfFailures` for rows that
            were rejected

            due to validation errors or process start failures.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkImportSummary'
        '400':
          description: Bad request — invalid file type, file too large, or unknown
            space ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                fileTooLarge:
                  summary: File exceeds 5 MB
                  value:
                    status: 400
                    error: Bad Request
                    message: File too large; maximum upload size is 5 MB
                invalidFileType:
                  summary: Non-xlsx content type
                  value:
                    status: 400
                    error: Bad Request
                    message: Invalid file type; only .xlsx files are accepted
                spaceNotFound:
                  summary: Unknown space ID
                  value:
                    status: 400
                    error: Bad Request
                    message: 'Space not found: 495b6aff-3e6c-4134-a042-ee4f6be45a06'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/spaces/{spaceId}/users/invitations:bulkImport/template:
    get:
      tags:
      - Space User Invitations
      summary: Download bulk invite Excel template
      description: "<div class='my-preview'><span>Preview: The API is in development\
        \ or testing phases and the interface could still change slightly.</span></div>\
        \ <br/> Returns a pre-formatted Excel (.xlsx) template for use with the bulk\
        \ import endpoint.\n\nThe template contains:\n- Identity columns: `firstName`,\
        \ `lastName`, `email`\n- One column per role: `space_admin`, `purchases_full`,\
        \ `purchases_limited`, `sales_full`,\n  `sales_limited`, `financial_full`,\
        \ `accountant`\n- Yes/no dropdown validation on every role column (rows 2–101)\n\
        - A sample row illustrating the expected format\n- Colour-coded headers: grey\
        \ for identity fields, blue for role columns\n\nUse the optional `language`\
        \ query parameter to receive column headers translated into the\nrequested\
        \ language. Supported values: `en` (default), `fr`.\n\nFill in the template\
        \ and upload it via\n`POST /v1/spaces/{spaceId}/users/invitations:bulkImport`.\n\
        \ <br/> Scope: []"
      operationId: downloadBulkImportTemplate
      parameters:
      - $ref: '#/components/parameters/SpaceIdPath'
      - name: language
        in: query
        required: false
        schema:
          type: string
          default: en
          enum:
          - en
          - fr
        description: Language code for template column header labels. Defaults to
          "en".
      responses:
        '200':
          description: Excel template file ready to fill in
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
              example: attachment; filename="bulk_invite_template.xlsx"
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    StartFormResponse:
      type: object
      properties:
        startForm:
          type: object
          description: The form definition for starting the registration process
        startFormVariables:
          type: object
          description: Pre-populated variables for the form
        registrationEndpoint:
          type: string
          description: The endpoint to submit the form to
        processDefinitionId:
          type: string
          description: The process definition ID for the registration process
      required:
      - startForm
      - startFormVariables
      - registrationEndpoint
      - processDefinitionId
    RegistrationRequest:
      type: object
      properties:
        processDefinitionId:
          type: string
          description: The process definition ID for the registration process
        values:
          type: object
          description: Form values including user information
          properties:
            ux:
              type: object
              description: UI-related values
            email:
              type: string
              description: User's email (may be in values or ux.email)
            firstName:
              type: string
              description: User's first name (may be in values or ux.firstName)
            lastName:
              type: string
              description: User's last name (may be in values or ux.lastName)
        outcome:
          type: string
          description: Optional form outcome
        state:
          type: string
          description: PKCE state parameter
        nonce:
          type: string
          description: PKCE nonce parameter
        code_challenge:
          type: string
          description: PKCE code challenge
        code_challenge_method:
          type: string
          description: PKCE code challenge method (usually S256)
      required:
      - processDefinitionId
      - values
      - state
      - nonce
      - code_challenge
      - code_challenge_method
    RegistrationResponse:
      type: object
      properties:
        processInstanceId:
          type: string
          description: The ID of the created process instance
        status:
          type: string
          description: Status of the registration process
        authorizationUrl:
          type: string
          description: URL to redirect the user for authentication
        redirectUrl:
          type: string
          description: URL to redirect the user for authentication (use in registrations
            API)
      required:
      - processInstanceId
      - status
      - authorizationUrl
    NewRegistrationRequest:
      type: object
      properties:
        country:
          type: string
          description: Required if up_product not provided; overrides up_product if
            both present
          example: BE
        up_product:
          type: string
          description: Optional - if provided, derives country and sourceApplication
          example: btxbe
        sourceApplication:
          type: string
          description: Source application identifier
          example: BTX
        email:
          type: string
          format: email
          description: User's email address (must be valid)
          example: user@example.com
        firstName:
          type: string
          description: User's first name
          example: John
        lastName:
          type: string
          description: User's last name
          example: Doe
        type:
          type: string
          description: Registration type (defaults to "platform" if not provided)
          enum:
          - platform
          - accounting
          - referral
          default: platform
          example: platform
        spaceId:
          type: string
          description: Required when type is "accounting" or "referral"
          example: space-123
        templateName:
          type: string
          description: Required when type is "accounting" or "referral"
          example: standard
        region:
          type: string
          description: Required when type is "accounting" or "referral"
        campaign:
          type: string
          description: Optional tracking parameter
        sig:
          type: string
          description: Optional enrollment context identifier
    AuthRequest:
      type: object
      properties:
        processInstanceId:
          type: string
          description: The process instance ID to authenticate for
        kc_idp_hint:
          type: string
          description: Optional identity provider hint (e.g., 'myid', 'google-up')
      required:
      - processInstanceId
    TmpAuthRequest:
      type: object
      properties:
        processInstanceId:
          type: string
          description: The process instance ID to authenticate for
        state:
          type: string
          description: PKCE state parameter
        nonce:
          type: string
          description: PKCE nonce parameter
        code_challenge:
          type: string
          description: PKCE code challenge
        code_challenge_method:
          type: string
          description: PKCE code challenge method (usually S256)
      required:
      - processInstanceId
      - state
      - nonce
      - code_challenge
      - code_challenge_method
    CallbackResponse:
      type: object
      properties:
        code:
          type: string
          description: The authorization code that was exchanged
        message:
          type: string
          description: Success message
      required:
      - code
      - message
    ProcessStartRequest:
      type: object
      properties:
        processKey:
          type: string
          description: The message name to start the process
        variables:
          type: object
          description: Process variables
          additionalProperties: true
      required:
      - processKey
    ProcessStartResponse:
      type: object
      properties:
        processInstanceId:
          type: string
          description: The ID of the created process instance
        processDefinitionId:
          type: string
          description: The process definition ID
        message:
          type: string
          description: Success message
      required:
      - processInstanceId
      - processDefinitionId
      - message
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Error message
      required:
      - status
      - error
      - message
    AuthErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Error message
      required:
      - status
      - error
      - message
    ProcessStartErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Error message
      required:
      - status
      - error
      - message
    CreateInvitationRequest:
      type: object
      properties:
        event:
          type: string
          description: The message start event name (e.g., 'inviteNewSpaceUserStart')
        invitee:
          $ref: '#/components/schemas/Invitee'
        space:
          $ref: '#/components/schemas/InvitationSpace'
        inviter:
          $ref: '#/components/schemas/Inviter'
      required:
      - event
      - invitee
      - space
      - inviter
    Invitee:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        permissions:
          $ref: '#/components/schemas/InviteePermissions'
      required:
      - firstName
      - lastName
      - email
    InviteePermissions:
      type: object
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/PermissionResource'
    PermissionResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        scopes:
          type: array
          items:
            type: string
        uxHint:
          type: boolean
        type:
          type: string
    InvitationSpace:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        region:
          type: string
        type:
          type: string
        entity:
          $ref: '#/components/schemas/SpaceEntity'
      required:
      - id
      - name
    SpaceEntity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        countryCode:
          type: string
    Inviter:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        subject:
          type: string
          description: Keycloak subject (user ID) of the inviter
      required:
      - firstName
      - lastName
      - email
    UpdateInvitationRequest:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
      required:
      - firstName
      - lastName
      - email
    InvitationResponse:
      type: object
      properties:
        processInstanceId:
          type: string
          description: The ID of the invitation process instance
        status:
          type: string
          description: Status of the invitation (started, updated)
      required:
      - processInstanceId
      - status
    InvitationReminderResponse:
      type: object
      properties:
        processInstanceId:
          type: string
          description: The ID of the invitation process instance
        reminderCount:
          type: integer
          description: The updated reminder count after sending the reminder
      required:
      - processInstanceId
      - reminderCount
    InvitationListResponse:
      type: object
      properties:
        invitations:
          type: array
          items:
            $ref: '#/components/schemas/InvitationSummary'
        total:
          type: integer
          description: Total number of invitations
      required:
      - invitations
      - total
    InvitationSummary:
      type: object
      properties:
        processInstanceId:
          type: string
        startTime:
          type: string
          format: date-time
        processVariables:
          type: object
          additionalProperties: true
          description: Process variables including invitee, space, and inviter details
    BulkImportSummary:
      type: object
      description: Summary of a bulk invitation import operation
      properties:
        totalRows:
          type: integer
          description: Total number of data rows processed
          example: 10
        numberOfSuccesses:
          type: integer
          description: Number of rows for which an invitation process was successfully
            started
          example: 8
        numberOfFailures:
          type: integer
          description: Number of rows that failed validation or could not start a
            process
          example: 2
      required:
      - totalRows
      - numberOfSuccesses
      - numberOfFailures
  parameters:
    SpaceIdPath:
      name: spaceId
      in: path
      description: The space ID
      required: true
      schema:
        type: string
        format: uuid
    ProcessInstanceIdPath:
      name: processInstanceId
      in: path
      description: The process instance ID
      required: true
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
tags:
- name: Registration
  description: API endpoints for starting and managing registration processes
- name: Authentication
  description: Authentication operations to login users and validate tokens
- name: Space User Invitations
  description: CRUD operations for managing space user invitations
- name: Process Management
  description: Low-level internal process control operations and utilities
security:
- oauth2:
  - openid
  - profile
  - email
