@celigo/api-specs 0.2.58 → 0.2.59

package/dist/fileserver.yml

@@ -0,0 +1,1316 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: File Server
+  description: Run a Celigo-hosted SFTP server whose partner accounts land files in Celigo Storage.
+  x-celigo-ai-guidance:
+    - |-
+      API for the account's Celigo-hosted SFTP file server: one server per environment
+      (`GET`/`PUT /v1/mft/fileserver`) and the partner accounts that log in to it
+      (`/v1/mft/fileserver/accounts`), each chrooted to a Celigo Storage folder. Requires a
+      full-access API token — folder-path-scoped and other restricted tokens answer 403
+      FILESERVER_FULL_ACCESS_TOKEN_REQUIRED on every route.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: File Server
+    description: |-
+      Each environment can run a Celigo-hosted SFTP file server. Enabling it claims a permanent `identifier` that becomes part of every partner login (`<username>@<identifier>`) and exposes the shared endpoint and host-key fingerprints partners need to connect. Partner accounts are created under the server, each with its own password and a Celigo Storage folder that becomes the account's root, so files a partner uploads appear in that folder and files placed there are what the partner can download. The account's license must include the file server add-on (`fileserver.enabled`), and every call needs a full-access API token.
+
+      ## File server and account schemas
+
+      {% openapi-schemas spec="fileserver" schemas="FileServer,FileServerAccount" grouped="true" %}
+paths:
+  /v1/mft/fileserver:
+    get:
+      x-internal: false
+      operationId: getFileServer
+      tags:
+        - File Server
+      summary: Get the environment's file server
+      description: |-
+        Returns the environment's SFTP file server: whether it is enabled, its permanent
+        `identifier`, the shared `endpoint` and host-key fingerprints partners connect
+        with, the `loginFormat`, and the effective `limits`. The server is a singleton
+        resolved from the caller's token — there is no id in the URL. An entitled
+        environment whose server was never enabled answers 404; an environment without
+        the file server add-on gets the reduced object (`entitled: false`, `endpoint`,
+        `limits`) with 200. Requires a full-access API token.
+      responses:
+        '200':
+          description: The file server, or the reduced object when the add-on is not licensed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileServer'
+              examples:
+                enabled:
+                  summary: Enabled server
+                  value:
+                    _id: 6ab1ef197cf630a06d774cf1
+                    enabled: true
+                    identifier: acme-logistics
+                    endpoint:
+                      hostname: sftp.integrator.io
+                      port: 22
+                    hostKeyFingerprints:
+                      - algorithm: ssh-ed25519
+                        fingerprint: SHA256:iYC+28MNea2ebwWmUMdnJRx0StabV53gZBmr6pto9fs
+                      - algorithm: rsa-sha2-512
+                        fingerprint: SHA256:0Qy3l7fJ2Zb1n8VtY4cH6uWkPq9rS2dE5gL7mN1oT3A
+                    loginFormat: <username>@acme-logistics
+                    limits:
+                      maxAccounts: 1000
+                      maxConcurrentSessionsPerAccount: 20
+                      maxFileSizeBytes: 10737418240
+                    entitled: true
+                notEntitled:
+                  summary: Environment without the add-on
+                  value:
+                    entitled: false
+                    endpoint:
+                      hostname: sftp.integrator.io
+                      port: 22
+                    limits:
+                      maxAccounts: 500
+                      maxConcurrentSessionsPerAccount: 10
+                      maxFileSizeBytes: 10737418240
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                scopedToken:
+                  value:
+                    errors:
+                      - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
+                        message: The file server management APIs require an API token with full access
+        '404':
+          description: The environment is entitled but its server has never been enabled (`FILESERVER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                neverEnabled:
+                  value:
+                    errors:
+                      - code: FILESERVER_NOT_FOUND
+                        message: The file server has not been enabled for this environment
+    put:
+      x-internal: false
+      operationId: updateFileServer
+      tags:
+        - File Server
+      summary: Enable or disable the file server
+      description: |-
+        Enables the environment's file server — creating it, and claiming the permanent
+        `identifier`, on the first call — or disables it. The body must carry `enabled`
+        as a JSON boolean; anything else is refused rather than interpreted, because a
+        disable ends every open partner session. Enabling also checks the environment's
+        Celigo Storage entitlement (partner uploads land there) and returns the current
+        `storageUsage` alongside the server. Disabling keeps the identifier and every
+        account, refuses new logins, and ends open sessions; repeating a disable is a
+        no-op. Sandbox environments cannot enable a server (403
+        `FILESERVER_NOT_ENTITLED`). Requires a full-access API token.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FileServerRequest'
+            examples:
+              enableFirstTime:
+                summary: First enable — claims the identifier
+                value:
+                  enabled: true
+                  identifier: acme-logistics
+              disable:
+                summary: Disable (identifier may be echoed, never changed)
+                value:
+                  enabled: false
+      responses:
+        '200':
+          description: The server after the change. Includes `storageUsage` when the call enabled it.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileServer'
+              examples:
+                disabled:
+                  summary: Disabled server
+                  value:
+                    _id: 6ab1ef197cf630a06d774cf1
+                    enabled: false
+                    identifier: acme-logistics
+                    endpoint:
+                      hostname: sftp.integrator.io
+                      port: 22
+                    hostKeyFingerprints:
+                      - algorithm: ssh-ed25519
+                        fingerprint: SHA256:iYC+28MNea2ebwWmUMdnJRx0StabV53gZBmr6pto9fs
+                    loginFormat: <username>@acme-logistics
+                    limits:
+                      maxAccounts: 1000
+                      maxConcurrentSessionsPerAccount: 20
+                      maxFileSizeBytes: 10737418240
+                    entitled: true
+        '400':
+          description: The body is not a JSON object sent as `application/json` (`FILESERVER_JSON_BODY_REQUIRED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notJson:
+                  value:
+                    errors:
+                      - code: FILESERVER_JSON_BODY_REQUIRED
+                        message: 'Request body must be a JSON object sent with Content-Type: application/json'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`),
+            the account's license lacks the file server add-on or the environment is a
+            sandbox (`FILESERVER_NOT_ENTITLED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notEntitled:
+                  value:
+                    errors:
+                      - code: FILESERVER_NOT_ENTITLED
+                        message: The file server add-on is not enabled for this account
+        '404':
+          description: A disable was sent for an environment whose server was never enabled (`FILESERVER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                neverEnabled:
+                  value:
+                    errors:
+                      - code: FILESERVER_NOT_FOUND
+                        message: The file server has not been enabled for this environment
+        '409':
+          description: The identifier is already held by another environment in the region (`FILESERVER_IDENTIFIER_TAKEN`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                taken:
+                  value:
+                    errors:
+                      - code: FILESERVER_IDENTIFIER_TAKEN
+                        message: This identifier is already in use
+        '422':
+          description: |-
+            `enabled` is missing or not a boolean (`FILESERVER_ENABLED_REQUIRED`), the
+            first-enable `identifier` is missing or malformed (`FILESERVER_IDENTIFIER_INVALID`),
+            or the body names an identifier different from the server's permanent one
+            (`FILESERVER_IDENTIFIER_IMMUTABLE`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                enabledRequired:
+                  value:
+                    errors:
+                      - code: FILESERVER_ENABLED_REQUIRED
+                        message: '"enabled" is required and must be a boolean'
+                identifierImmutable:
+                  value:
+                    errors:
+                      - code: FILESERVER_IDENTIFIER_IMMUTABLE
+                        message: The file server identifier cannot be changed
+                identifierInvalid:
+                  value:
+                    errors:
+                      - code: FILESERVER_IDENTIFIER_INVALID
+                        message: Identifier must be 3-30 lowercase letters, digits or hyphens, with no leading or trailing hyphen
+        '503':
+          description: |-
+            Enabling requires a live check of the environment's Celigo Storage entitlement;
+            when that check cannot complete the enable is refused with
+            `FILESERVER_STORAGE_UNAVAILABLE` and nothing changes. Retry later.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                storageUnavailable:
+                  value:
+                    errors:
+                      - code: FILESERVER_STORAGE_UNAVAILABLE
+                        message: 'File storage is temporarily unavailable: storage entitlement could not be verified'
+  /v1/mft/fileserver/accounts:
+    get:
+      x-internal: false
+      operationId: listFileServerAccounts
+      tags:
+        - File Server
+      summary: List file server accounts
+      description: |-
+        Returns the environment's partner accounts oldest first, wrapped in an
+        `accounts` array, with `overCap` computed for each against the current
+        `limits.maxAccounts`. Paging is cursor-based: when more accounts follow, the
+        `Link` header carries a `rel="next"` URL whose `after` cursor (and `pageSize`)
+        fetch the next page, and a page reached through `after` also offers
+        `rel="prev"`. Cursors are opaque — pass them back exactly as received; anything
+        else answers 400 `FILESERVER_INVALID_CURSOR`. Accounts stay listable after the
+        add-on is removed from the license; only writes are blocked then. Requires a
+        full-access API token and a server that has been enabled at least once.
+      parameters:
+        - name: pageSize
+          in: query
+          required: false
+          description: Accounts per page. Values outside the range are clamped rather than rejected.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 100
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: Opaque cursor from the previous page's `rel="next"` link. Returns the accounts created after it.
+          schema:
+            type: string
+        - name: before
+          in: query
+          required: false
+          description: Opaque cursor from a page's `rel="prev"` link. Returns the accounts created before it. Ignored when `after` is also sent.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: One page of accounts.
+          headers:
+            Link:
+              description: |-
+                RFC 8288 pagination links: `<…?after=…&pageSize=…>; rel="next"` when more
+                accounts follow, `<…?before=…&pageSize=…>; rel="prev"` when the page was
+                reached through a cursor. Absent when the whole list fits in one page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - accounts
+                properties:
+                  accounts:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/FileServerAccount'
+              examples:
+                default:
+                  value:
+                    accounts:
+                      - _id: 6ab1f2737cf630a06d774d09
+                        username: northwind-edi
+                        login: northwind-edi@acme-logistics
+                        _homeFolderId: 6ab1f25daa3e7ed226ea3f25
+                        homeFolderPath: Partners/Northwind/Inbound
+                        enabled: true
+                        passwordSet: true
+                        overCap: false
+                        lastConnectedAt: '2026-09-22T14:35:31.646Z'
+                        createdAt: '2026-09-22T03:13:56.060Z'
+                        lastModified: '2026-09-22T14:35:31.648Z'
+        '400':
+          description: The `after` or `before` cursor is not one this list issued (`FILESERVER_INVALID_CURSOR`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidCursor:
+                  value:
+                    errors:
+                      - code: FILESERVER_INVALID_CURSOR
+                        message: Invalid pagination cursor
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                scopedToken:
+                  value:
+                    errors:
+                      - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
+                        message: The file server management APIs require an API token with full access
+        '422':
+          description: The environment's server has never been enabled (`FILESERVER_NOT_ENABLED`); a disabled server is still manageable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notEnabled:
+                  value:
+                    errors:
+                      - code: FILESERVER_NOT_ENABLED
+                        message: Enable the file server before managing accounts
+    post:
+      x-internal: false
+      operationId: createFileServerAccount
+      tags:
+        - File Server
+      summary: Create a file server account
+      description: |-
+        Creates an enabled partner account with the given `username`, `password`, and
+        Celigo Storage home folder, and returns it (the password is never returned).
+        Checks run in order and the first failure is answered: username shape, password
+        presence, home-folder presence, the enabled-account cap, then the folder is
+        verified to be an active folder in this environment. Requires a full-access API
+        token, the file server add-on on the license, and a server that has been enabled
+        at least once.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FileServerAccountCreateRequest'
+            examples:
+              default:
+                value:
+                  username: northwind-edi
+                  password: Nw-Inbound-2026!x
+                  _homeFolderId: 6ab1f25daa3e7ed226ea3f25
+      responses:
+        '201':
+          description: The new account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileServerAccount'
+              examples:
+                default:
+                  value:
+                    _id: 6ab1f2737cf630a06d774d09
+                    username: northwind-edi
+                    login: northwind-edi@acme-logistics
+                    _homeFolderId: 6ab1f25daa3e7ed226ea3f25
+                    homeFolderPath: Partners/Northwind/Inbound
+                    enabled: true
+                    passwordSet: true
+                    overCap: false
+                    lastConnectedAt: null
+                    createdAt: '2026-09-22T03:13:56.060Z'
+                    lastModified: '2026-09-22T03:13:56.060Z'
+        '400':
+          description: The body is not a JSON object sent as `application/json` (`FILESERVER_JSON_BODY_REQUIRED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notJson:
+                  value:
+                    errors:
+                      - code: FILESERVER_JSON_BODY_REQUIRED
+                        message: 'Request body must be a JSON object sent with Content-Type: application/json'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`);
+            the license lacks the add-on or the environment is a sandbox
+            (`FILESERVER_NOT_ENTITLED`); or the environment already holds
+            `limits.maxAccounts` enabled accounts (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                capReached:
+                  value:
+                    errors:
+                      - code: FILESERVER_MAX_ACCOUNTS_EXCEEDED
+                        message: The maximum number of enabled accounts for this environment has been reached
+        '409':
+          description: Another account in this environment already has that username, enabled or not (`FILESERVER_USERNAME_TAKEN`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                usernameTaken:
+                  value:
+                    errors:
+                      - code: FILESERVER_USERNAME_TAKEN
+                        message: This username is already in use on this file server
+        '422':
+          description: |-
+            The server has never been enabled (`FILESERVER_NOT_ENABLED`); `username` is
+            missing or malformed (`FILESERVER_USERNAME_INVALID`); `password` is missing
+            (`FILESERVER_LAST_CREDENTIAL`) or too weak (`FILESERVER_WEAK_PASSWORD`);
+            `_homeFolderId` is missing or does not exist in this environment
+            (`FILESERVER_HOME_FOLDER_NOT_FOUND`) or is a file rather than an active folder
+            (`FILESERVER_HOME_FOLDER_NOT_FOLDER`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                usernameInvalid:
+                  value:
+                    errors:
+                      - code: FILESERVER_USERNAME_INVALID
+                        message: Username must be 3-32 lowercase letters, digits or hyphens, with no leading or trailing hyphen
+                passwordMissing:
+                  value:
+                    errors:
+                      - code: FILESERVER_LAST_CREDENTIAL
+                        message: An enabled account must have a password
+                homeFolderMissing:
+                  value:
+                    errors:
+                      - code: FILESERVER_HOME_FOLDER_NOT_FOUND
+                        message: The home folder does not exist in this environment
+        '503':
+          description: |-
+            The home folder is verified against Celigo Storage at create time; when that
+            check cannot complete the create is refused with `FILESERVER_STORAGE_UNAVAILABLE`
+            and no account is made. Retry later.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                storageUnavailable:
+                  value:
+                    errors:
+                      - code: FILESERVER_STORAGE_UNAVAILABLE
+                        message: 'File storage is temporarily unavailable: home-folder validation failed'
+  /v1/mft/fileserver/accounts/{_id}:
+    get:
+      x-internal: false
+      operationId: getFileServerAccount
+      tags:
+        - File Server
+      summary: Get a file server account
+      description: |-
+        Returns one partner account with `overCap` computed against the current cap.
+        An id that is unknown, belongs to another environment, or is not a valid
+        identifier all answer the same 404. Requires a full-access API token and a
+        server that has been enabled at least once.
+      parameters:
+        - $ref: '#/components/parameters/AccountId'
+      responses:
+        '200':
+          description: The account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileServerAccount'
+              examples:
+                default:
+                  value:
+                    _id: 6ab1f2737cf630a06d774d09
+                    username: northwind-edi
+                    login: northwind-edi@acme-logistics
+                    _homeFolderId: 6ab1f25daa3e7ed226ea3f25
+                    homeFolderPath: Partners/Northwind/Inbound
+                    enabled: true
+                    passwordSet: true
+                    overCap: false
+                    lastConnectedAt: '2026-09-22T14:35:31.646Z'
+                    createdAt: '2026-09-22T03:13:56.060Z'
+                    lastModified: '2026-09-22T14:35:31.648Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-full-access-required'
+        '404':
+          $ref: '#/components/responses/404-account-not-found'
+        '422':
+          $ref: '#/components/responses/422-server-not-enabled'
+    put:
+      x-internal: false
+      operationId: updateFileServerAccount
+      tags:
+        - File Server
+      summary: Update a file server account
+      description: |-
+        Changes the fields sent and returns the account; fields left out keep their
+        values, and `{}` returns the account unchanged. Renaming keeps `_id` and
+        updates `login`. Moving the home folder is verified against Celigo Storage and
+        ends the account's open sessions, as does disabling it. Re-enabling counts
+        against `limits.maxAccounts` and requires a password to be set. The password
+        cannot be changed here — use `POST /v1/mft/fileserver/accounts/{_id}/password`.
+        Requires a full-access API token, the file server add-on on the license, and a
+        server that has been enabled at least once.
+      parameters:
+        - $ref: '#/components/parameters/AccountId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FileServerAccountUpdateRequest'
+            examples:
+              disable:
+                summary: Disable the account
+                value:
+                  enabled: false
+              rename:
+                summary: Rename
+                value:
+                  username: northwind-edi-2
+      responses:
+        '200':
+          description: The account after the change.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileServerAccount'
+              examples:
+                disabled:
+                  value:
+                    _id: 6ab1f2737cf630a06d774d09
+                    username: northwind-edi
+                    login: northwind-edi@acme-logistics
+                    _homeFolderId: 6ab1f25daa3e7ed226ea3f25
+                    homeFolderPath: Partners/Northwind/Inbound
+                    enabled: false
+                    passwordSet: true
+                    overCap: false
+                    lastConnectedAt: '2026-09-22T14:35:31.646Z'
+                    createdAt: '2026-09-22T03:13:56.060Z'
+                    lastModified: '2026-09-25T01:40:12.004Z'
+        '400':
+          description: The body is not a JSON object sent as `application/json` (`FILESERVER_JSON_BODY_REQUIRED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notJson:
+                  value:
+                    errors:
+                      - code: FILESERVER_JSON_BODY_REQUIRED
+                        message: 'Request body must be a JSON object sent with Content-Type: application/json'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`);
+            the license lacks the add-on or the environment is a sandbox
+            (`FILESERVER_NOT_ENTITLED`); or re-enabling would exceed `limits.maxAccounts`
+            (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                capReached:
+                  value:
+                    errors:
+                      - code: FILESERVER_MAX_ACCOUNTS_EXCEEDED
+                        message: The maximum number of enabled accounts for this environment has been reached
+        '404':
+          $ref: '#/components/responses/404-account-not-found'
+        '409':
+          description: The new username belongs to another account in this environment (`FILESERVER_USERNAME_TAKEN`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                usernameTaken:
+                  value:
+                    errors:
+                      - code: FILESERVER_USERNAME_TAKEN
+                        message: This username is already in use on this file server
+        '422':
+          description: |-
+            The server has never been enabled (`FILESERVER_NOT_ENABLED`); `username` is
+            malformed (`FILESERVER_USERNAME_INVALID`); `enabled` is present but not a
+            boolean (`FILESERVER_ENABLED_REQUIRED`); re-enabling an account with no
+            password (`FILESERVER_LAST_CREDENTIAL`); or the new home folder does not exist
+            or is not an active folder (`FILESERVER_HOME_FOLDER_NOT_FOUND`,
+            `FILESERVER_HOME_FOLDER_NOT_FOLDER`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                enabledRequired:
+                  value:
+                    errors:
+                      - code: FILESERVER_ENABLED_REQUIRED
+                        message: '"enabled" is required and must be a boolean'
+                noPassword:
+                  value:
+                    errors:
+                      - code: FILESERVER_LAST_CREDENTIAL
+                        message: An enabled account must have a password
+        '503':
+          description: The new home folder could not be verified against Celigo Storage (`FILESERVER_STORAGE_UNAVAILABLE`); nothing changed. Retry later.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                storageUnavailable:
+                  value:
+                    errors:
+                      - code: FILESERVER_STORAGE_UNAVAILABLE
+                        message: 'File storage is temporarily unavailable: home-folder validation failed'
+    delete:
+      x-internal: false
+      operationId: deleteFileServerAccount
+      tags:
+        - File Server
+      summary: Delete a file server account
+      description: |-
+        Permanently removes the account and ends any session it has open. The home
+        folder and its files are untouched. There is no recycle bin for accounts —
+        recreate one to restore access. Requires a full-access API token, the file
+        server add-on on the license, and a server that has been enabled at least once.
+      parameters:
+        - $ref: '#/components/parameters/AccountId'
+      responses:
+        '204':
+          description: Account deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-full-access-required'
+        '404':
+          $ref: '#/components/responses/404-account-not-found'
+        '422':
+          $ref: '#/components/responses/422-server-not-enabled'
+  /v1/mft/fileserver/accounts/{_id}/password:
+    post:
+      x-internal: false
+      operationId: setFileServerAccountPassword
+      tags:
+        - File Server
+      summary: Set or clear an account's password
+      description: |-
+        Sets a new password for the partner account, or clears it when `password` is
+        `null`. Clearing is refused while the account is enabled, because an enabled
+        account must keep a credential — disable it first. Either change ends the
+        account's open sessions and stamps the change for session revalidation. The
+        route answers 204 and never echoes a credential; `passwordSet` on the account
+        reflects the result. Requires a full-access API token, the file server add-on on
+        the license, and a server that has been enabled at least once.
+      parameters:
+        - $ref: '#/components/parameters/AccountId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FileServerAccountPasswordRequest'
+            examples:
+              rotate:
+                summary: Set a new password
+                value:
+                  password: Nw-Inbound-2026!y
+              clear:
+                summary: Clear the password of a disabled account
+                value:
+                  password: null
+      responses:
+        '204':
+          description: Password set or cleared. No body.
+        '400':
+          description: The body is not a JSON object sent as `application/json` (`FILESERVER_JSON_BODY_REQUIRED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notJson:
+                  value:
+                    errors:
+                      - code: FILESERVER_JSON_BODY_REQUIRED
+                        message: 'Request body must be a JSON object sent with Content-Type: application/json'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-full-access-required'
+        '404':
+          $ref: '#/components/responses/404-account-not-found'
+        '422':
+          description: |-
+            The server has never been enabled (`FILESERVER_NOT_ENABLED`); the new password
+            breaks the policy or `password` is neither a string nor `null`
+            (`FILESERVER_WEAK_PASSWORD` — the message names the rule); or `null` was sent
+            for an enabled account (`FILESERVER_LAST_CREDENTIAL`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                weakPassword:
+                  value:
+                    errors:
+                      - code: FILESERVER_WEAK_PASSWORD
+                        message: Password must be a string (or null to clear).
+                lastCredential:
+                  value:
+                    errors:
+                      - code: FILESERVER_LAST_CREDENTIAL
+                        message: An enabled account must have a password
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    FileServer:
+      type: object
+      description: |-
+        The environment's SFTP file server — one per environment, resolved from the
+        caller's token (no id in the URL). Partners connect to `endpoint`, verify the
+        server against `hostKeyFingerprints`, and log in as `<username>@<identifier>`
+        with a partner account's password. On an entitled environment where the server
+        has never been enabled, reads answer 404 rather than returning this object; an
+        environment without the file server add-on gets a reduced object carrying only
+        `entitled: false`, `endpoint`, and `limits`.
+      required:
+        - endpoint
+        - limits
+        - entitled
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Identifier of the file server record. Absent on the reduced object returned to an environment without the add-on.
+          examples:
+            - 6ab1ef197cf630a06d774cf1
+        enabled:
+          type: boolean
+          description: |-
+            When true, partners can connect and every enabled account can log in. Setting
+            it to false on `PUT` keeps the identifier and all accounts, refuses new
+            logins, and ends any session currently open; the same body sent again is a
+            no-op. Absent on the reduced object returned to an environment without the
+            add-on.
+          examples:
+            - true
+        identifier:
+          type: string
+          minLength: 3
+          maxLength: 30
+          pattern: ^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$
+          description: |-
+            The environment's name inside every partner login (`<username>@<identifier>`),
+            unique across the region. Chosen on the `PUT` that first enables the server,
+            lowercased on save, and permanent afterwards — a later `PUT` may echo it but a
+            different value is rejected with 422 `FILESERVER_IDENTIFIER_IMMUTABLE`.
+            Absent on the reduced object returned to an environment without the add-on.
+          examples:
+            - acme-logistics
+        endpoint:
+          type: object
+          readOnly: true
+          description: Where partners connect. Shared by every environment in the region; the `identifier` in the login routes the session.
+          required:
+            - hostname
+            - port
+          properties:
+            hostname:
+              type: string
+              description: SFTP host partners connect to.
+              examples:
+                - sftp.integrator.io
+            port:
+              type: integer
+              description: TCP port of the SFTP listener.
+              examples:
+                - 22
+        hostKeyFingerprints:
+          type: array
+          readOnly: true
+          description: |-
+            SHA-256 fingerprints of the server's SSH host keys, one per algorithm, for
+            partners to pin before their first connection. Absent on the reduced object
+            returned to an environment without the add-on.
+          items:
+            type: object
+            required:
+              - algorithm
+              - fingerprint
+            properties:
+              algorithm:
+                type: string
+                description: SSH host-key algorithm the fingerprint belongs to.
+                examples:
+                  - ssh-ed25519
+              fingerprint:
+                type: string
+                description: Fingerprint in OpenSSH `SHA256:<base64>` form.
+                examples:
+                  - SHA256:iYC+28MNea2ebwWmUMdnJRx0StabV53gZBmr6pto9fs
+        loginFormat:
+          type: string
+          readOnly: true
+          description: Template for partner usernames on this server — the account's `username`, `@`, then the server `identifier`. Absent on the reduced object returned to an environment without the add-on.
+          examples:
+            - <username>@acme-logistics
+        limits:
+          type: object
+          readOnly: true
+          description: Effective ceilings for this environment, from the license where it sets them and from platform defaults otherwise.
+          required:
+            - maxAccounts
+            - maxConcurrentSessionsPerAccount
+            - maxFileSizeBytes
+          properties:
+            maxAccounts:
+              type: integer
+              minimum: 0
+              description: Number of enabled accounts the environment may hold. Creating or re-enabling an account past it answers 403 `FILESERVER_MAX_ACCOUNTS_EXCEEDED`.
+              examples:
+                - 1000
+            maxConcurrentSessionsPerAccount:
+              type: integer
+              minimum: 0
+              description: Sessions one account may hold open at once; further logins are refused until one closes.
+              examples:
+                - 20
+            maxFileSizeBytes:
+              type: integer
+              minimum: 0
+              description: Largest single file a partner may upload, in bytes.
+              examples:
+                - 10737418240
+        entitled:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, the account's license includes the file server add-on
+            (`fileserver.enabled`) and the server can be enabled and managed. When false
+            the object is reduced to `endpoint` and `limits`, and every `PUT` and every
+            account write answers 403 `FILESERVER_NOT_ENTITLED`; existing accounts stay
+            readable.
+          examples:
+            - true
+        storageUsage:
+          type: object
+          readOnly: true
+          additionalProperties: true
+          description: |-
+            Only present on the `PUT` response that enables the server: the environment's
+            Celigo Storage usage as `GET /v1/storage/usage` reports it, checked at enable
+            time because partner uploads land in that storage.
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    FileServerRequest:
+      type: object
+      description: |-
+        Body of `PUT /v1/mft/fileserver`. `enabled` must be an explicit boolean — an
+        absent or non-boolean value is rejected (422 `FILESERVER_ENABLED_REQUIRED`)
+        rather than read as a disable, because a disable ends every open partner
+        session.
+      required:
+        - enabled
+      properties:
+        enabled:
+          type: boolean
+          description: |-
+            When true, enables the server (creating it on the first call). When false,
+            disables it: the identifier and all accounts are kept, new logins are refused,
+            and open sessions end.
+          examples:
+            - true
+        identifier:
+          type: string
+          minLength: 3
+          maxLength: 30
+          pattern: ^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$
+          description: |-
+            Required on the `PUT` that first enables the server; permanent afterwards.
+            Lowercased on save and unique across the region (409
+            `FILESERVER_IDENTIFIER_TAKEN` when another environment holds it). On later
+            calls omit it or echo the current value — any other value answers 422
+            `FILESERVER_IDENTIFIER_IMMUTABLE`, even on a disable.
+          examples:
+            - acme-logistics
+      x-celigo-ai-guidance:
+        - |-
+          Always send enabled as a JSON boolean: {} and {"enabled": "true"} both fail with 422
+          FILESERVER_ENABLED_REQUIRED, and a non-JSON body fails with 400
+          FILESERVER_JSON_BODY_REQUIRED. Never send a new identifier for an existing server —
+          it is rejected with 422 FILESERVER_IDENTIFIER_IMMUTABLE even when enabled is unchanged.
+    FileServerAccount:
+      type: object
+      description: |-
+        A partner login on the environment's file server. The partner authenticates as
+        `login` with the password set through `POST /v1/mft/fileserver/accounts/{_id}/password`
+        (never returned — `passwordSet` only says whether one exists) and sees the
+        Celigo Storage folder `_homeFolderId` as the root of the session. Disabling the
+        account, deleting it, changing its password, or moving its home folder ends any
+        session it has open.
+      required:
+        - _id
+        - username
+        - login
+        - _homeFolderId
+        - enabled
+        - passwordSet
+        - overCap
+        - createdAt
+        - lastModified
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Identifier of the account. Not derived from the username, so a rename keeps it.
+          examples:
+            - 6ab1f2737cf630a06d774d09
+        username:
+          type: string
+          minLength: 3
+          maxLength: 32
+          pattern: ^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$
+          description: |-
+            Partner's name on this server, unique per environment even while the account
+            is disabled. Lowercased on save; a value outside the pattern is rejected with
+            422 `FILESERVER_USERNAME_INVALID` and a name another account already holds
+            with 409 `FILESERVER_USERNAME_TAKEN`.
+          examples:
+            - northwind-edi
+        login:
+          type: string
+          readOnly: true
+          description: The exact SFTP username the partner types — `username`, `@`, then the server `identifier`.
+          examples:
+            - northwind-edi@acme-logistics
+        _homeFolderId:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Celigo Storage folder that is the root of every session for this account —
+            the partner can reach nothing outside it. Must be an active folder in the same
+            environment; otherwise the write answers 422 `FILESERVER_HOME_FOLDER_NOT_FOUND`
+            or `FILESERVER_HOME_FOLDER_NOT_FOLDER`. Moving an account to another folder
+            ends its open sessions.
+          examples:
+            - 6ab1f25daa3e7ed226ea3f25
+        homeFolderPath:
+          type:
+            - string
+            - 'null'
+          readOnly: true
+          description: |-
+            Breadcrumb path of `_homeFolderId` from the storage root, for display. Null
+            when the path could not be resolved for this response — the folder id is
+            still authoritative.
+          examples:
+            - Partners/Northwind/Inbound
+        enabled:
+          type: boolean
+          description: |-
+            When true, the partner can log in. Disabling keeps the account and its password
+            but refuses logins and ends open sessions; re-enabling counts against
+            `limits.maxAccounts` and requires a password to be set (422
+            `FILESERVER_LAST_CREDENTIAL` otherwise). New accounts start enabled.
+          examples:
+            - true
+        passwordSet:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, the account has a password. The password itself is never returned by
+            any route; change or clear it through `POST /v1/mft/fileserver/accounts/{_id}/password`.
+            Clearing is allowed only while the account is disabled.
+          examples:
+            - true
+        overCap:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, this enabled account ranks above the environment's `limits.maxAccounts`
+            after the cap was lowered, so its logins are refused until enough other accounts
+            are disabled or deleted. Computed on every read; always false while the
+            environment is within its cap.
+          examples:
+            - false
+        lastConnectedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp of the partner's most recent successful login. Null until the first one.
+          examples:
+            - '2026-09-22T14:35:31.646Z'
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the account was created.
+          examples:
+            - '2026-09-22T03:13:56.060Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp of the last change to the account, including logins updating `lastConnectedAt`.
+          examples:
+            - '2026-09-22T14:35:31.648Z'
+    FileServerAccountCreateRequest:
+      type: object
+      description: |-
+        Body of `POST /v1/mft/fileserver/accounts`. The account is created enabled, so
+        all three fields are needed for a partner to be able to log in. Checks run in
+        this order and the first failure is returned: `username` shape, `password`
+        presence, `_homeFolderId` presence, the enabled-account cap, then the folder's
+        existence and type in this environment.
+      required:
+        - username
+        - password
+        - _homeFolderId
+      properties:
+        username:
+          type: string
+          minLength: 3
+          maxLength: 32
+          pattern: ^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$
+          description: |-
+            Partner's name on this server; the SFTP login becomes `<username>@<identifier>`.
+            Lowercased on save. Unique per environment, including against disabled accounts
+            (409 `FILESERVER_USERNAME_TAKEN`).
+          examples:
+            - northwind-edi
+        password:
+          type: string
+          format: password
+          minLength: 12
+          maxLength: 256
+          description: |-
+            Partner's password. Needs upper- and lower-case letters, a digit, and a symbol;
+            anything weaker is rejected with 422 `FILESERVER_WEAK_PASSWORD` and the message
+            names the rule broken. Never returned by any route — rotate or clear it later
+            through `POST /v1/mft/fileserver/accounts/{_id}/password`.
+          examples:
+            - Nw-Inbound-2026!x
+        _homeFolderId:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Celigo Storage folder that becomes the root of the partner's sessions. Must be
+            an active folder in this environment — create one with
+            `POST /v1/storage/items` first.
+          examples:
+            - 6ab1f25daa3e7ed226ea3f25
+      x-celigo-ai-guidance:
+        - |-
+          Send username, password and _homeFolderId together. A missing username answers 422
+          FILESERVER_USERNAME_INVALID (same code as a malformed one), a missing password 422
+          FILESERVER_LAST_CREDENTIAL, and a missing _homeFolderId 422
+          FILESERVER_HOME_FOLDER_NOT_FOUND — each before anything is created.
+    FileServerAccountUpdateRequest:
+      type: object
+      description: |-
+        Body of `PUT /v1/mft/fileserver/accounts/{_id}`. Partial: only the fields sent
+        change, and an empty object is a no-op that returns the current account. The
+        password is not part of this body — use the dedicated password route.
+      properties:
+        username:
+          type: string
+          minLength: 3
+          maxLength: 32
+          pattern: ^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$
+          description: New name for the partner; `login` changes with it and `_id` does not. Same shape and uniqueness rules as on create.
+          examples:
+            - northwind-edi-2
+        _homeFolderId:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: Move the account to another active folder in this environment. Ends the account's open sessions, which were rooted in the old folder.
+          examples:
+            - 6ab1f25daa3e7ed226ea3f25
+        enabled:
+          type: boolean
+          description: |-
+            Must be a JSON boolean when present (422 `FILESERVER_ENABLED_REQUIRED` for
+            `"false"` or other non-booleans). False keeps the account but refuses logins
+            and ends open sessions. True re-enables it — subject to `limits.maxAccounts`
+            (403 `FILESERVER_MAX_ACCOUNTS_EXCEEDED`) and only if a password is set (422
+            `FILESERVER_LAST_CREDENTIAL`).
+          examples:
+            - false
+    FileServerAccountPasswordRequest:
+      type: object
+      description: |-
+        Body of `POST /v1/mft/fileserver/accounts/{_id}/password`. Sets a new password or,
+        with `null`, clears the current one. Either change ends the account's open
+        sessions. Nothing is echoed back — the route answers 204.
+      required:
+        - password
+      properties:
+        password:
+          type:
+            - string
+            - 'null'
+          format: password
+          description: |-
+            The new password, meeting the same policy as on create (422
+            `FILESERVER_WEAK_PASSWORD` otherwise), or `null` to remove the password —
+            allowed only while the account is disabled, because an enabled account must
+            keep a credential (422 `FILESERVER_LAST_CREDENTIAL`). Any other type answers
+            422 `FILESERVER_WEAK_PASSWORD` with the message "Password must be a string (or
+            null to clear)."
+          examples:
+            - Nw-Inbound-2026!y
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    403-full-access-required:
+      description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or the license lacks the add-on / the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            scopedToken:
+              value:
+                errors:
+                  - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
+                    message: The file server management APIs require an API token with full access
+    404-account-not-found:
+      description: No account with this id in the caller's environment, or the id is not a valid identifier (`FILESERVER_ACCOUNT_NOT_FOUND`).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            notFound:
+              value:
+                errors:
+                  - code: FILESERVER_ACCOUNT_NOT_FOUND
+                    message: File server account not found
+    422-server-not-enabled:
+      description: The environment's server has never been enabled (`FILESERVER_NOT_ENABLED`); a disabled server is still manageable.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            notEnabled:
+              value:
+                errors:
+                  - code: FILESERVER_NOT_ENABLED
+                    message: Enable the file server before managing accounts
+  parameters:
+    AccountId:
+      name: _id
+      in: path
+      required: true
+      description: The file server account. A malformed value answers 404 like an unknown one.
+      schema:
+        type: string
+        format: objectId
+        examples:
+          - 6ab1f2737cf630a06d774d09
+x-internal: false
+x-enable-proxy: true