openapi: 3.0.0
paths:
  /version/export/{tenantId}:
    get:
      description: >-
        Export the full configuration of the specified tenant in JSON or ZIP
        format.
      operationId: VersionController_exportVersion
      parameters:
        - name: tenantId
          required: true
          in: path
          description: >-
            Tenant ID specifying the environment from which the configuration is
            exported
          schema:
            type: string
        - name: format
          required: true
          in: query
          description: Exported data format
          schema:
            enum:
              - json
              - zip
            type: string
      responses:
        '200':
          description: >-
            Export completed. Returns the exported tenant configuration payload,
            including application data, external connections, and alias
            references.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdoExportUnifiedResponseDto'
        '400':
          description: 'Error: Bad Request'
          content:
            application/json:
              example:
                statusCode: 400
                message: Sample error message
                error: Bad Request
        '401':
          description: 'Error: Unauthorized'
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
        '500':
          description: 'Error: Internal Server Error'
          content:
            application/json:
              example:
                statusCode: 500
                message: Internal server error
      security:
        - bearer: []
      summary: Export configuration
  /version/import/{tenantId}:
    post:
      description: Import tenant configuration data with version and integrity validation.
      operationId: VersionController_import
      parameters:
        - name: tenantId
          required: true
          in: path
          description: >-
            Tenant ID specifying the environment into which the configuration is
            imported
          schema:
            type: string
        - name: format
          required: true
          in: query
          description: Expected format of the file to import
          schema:
            enum:
              - json
              - zip
            type: string
      requestBody:
        required: true
        description: Exported data to import
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdoExportUnifiedResponseDto'
      responses:
        '201':
          description: >-
            Import completed successfully. Returns the overall status and
            details of the import process
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportUnifiedResponseDto'
        '400':
          description: 'Error: Bad Request'
          content:
            application/json:
              example:
                statusCode: 400
                message: Sample error message
                error: Bad Request
        '401':
          description: 'Error: Unauthorized'
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
        '500':
          description: 'Error: Internal Server Error'
          content:
            application/json:
              example:
                statusCode: 500
                message: Internal server error
      security:
        - bearer: []
      summary: Import configuration
  /version/force-import/{tenantId}:
    post:
      description: >-
        Force import tenant configuration, skipping version checks but
        validating structural integrity.
      operationId: VersionController_forceImport
      parameters:
        - name: tenantId
          required: true
          in: path
          description: >-
            Tenant ID specifying the environment into which the configuration is
            force-imported
          schema:
            type: string
        - name: format
          required: true
          in: query
          description: Expected format of the file to import
          schema:
            enum:
              - json
              - zip
            type: string
      requestBody:
        required: true
        description: Exported data to force import
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdoExportUnifiedResponseDto'
      responses:
        '201':
          description: Force import completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportUnifiedResponseDto'
        '400':
          description: 'Error: Bad Request'
          content:
            application/json:
              example:
                statusCode: 400
                message: Sample error message
                error: Bad Request
        '401':
          description: 'Error: Unauthorized'
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
        '500':
          description: 'Error: Internal Server Error'
          content:
            application/json:
              example:
                statusCode: 500
                message: Internal server error
      security:
        - bearer: []
      summary: Force import
  /version/validate/{tenantId}:
    post:
      description: >-
        Validate the structure and version of exported data without applying it
        to the target tenant
      operationId: VersionController_validate
      parameters:
        - name: tenantId
          required: true
          in: path
          description: >-
            Tenant ID specifying the environment against which the exported data
            is validated
          schema:
            type: string
        - name: format
          required: true
          in: query
          description: Format of data to validate
          schema:
            enum:
              - json
              - zip
            type: string
      requestBody:
        required: true
        description: Exported data to validate
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdoExportUnifiedResponseDto'
      responses:
        '201':
          description: >-
            Validation completed. Returns validation result and any detected
            errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationUnifiedResponseDto'
        '400':
          description: 'Error: Bad Request'
          content:
            application/json:
              example:
                statusCode: 400
                message: Sample error message
                error: Bad Request
        '401':
          description: 'Error: Unauthorized'
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
        '500':
          description: 'Error: Internal Server Error'
          content:
            application/json:
              example:
                statusCode: 500
                message: Internal server error
      security:
        - bearer: []
      summary: Validate structure
info:
  title: Version Management
  description: >-
    Safely promote changes between tenant environments. With Version Management
    APIs, you can export, validate, import, and force-import tenant
    configurations while ensuring version and integrity checks.
  version: ''
servers:
  - url: https://version-management.sbx.transmitsecurity.io
    description: Sandbox environment
  - url: https://version-management.transmitsecurity.io
    description: Production environment (US)
  - url: https://version-management.ca.transmitsecurity.io
    description: Production environment (CA)
  - url: https://version-management.eu.transmitsecurity.io
    description: Production environment (EU)
  - url: https://version-management.au.transmitsecurity.io
    description: Production environment (AU)
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: >-
        An access token generated by the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken) using the
        management app credentials. Note that this token should not target any
        specific resource.
  schemas:
    IdoExportDataResponseDto:
      type: object
      properties:
        path:
          type: string
          description: The path to the resource
        data:
          type: object
          description: The data of the resource
        category:
          type: string
          description: The category of the resource
        type:
          type: string
          description: The type of the resource
      required:
        - path
        - data
        - category
        - type
    IdentityData:
      type: object
      properties:
        alias:
          type: string
          description: >-
            Alias of the referenced resource. Must match an existing resource
            alias in the target tenant
        version:
          type: string
          description: >-
            Version identifier of the referenced resource. Used to ensure
            compatibility during import
      required:
        - alias
        - version
    IdoExportUnifiedResponseDto:
      type: object
      properties:
        version:
          type: string
          description: Version tag of the exported configuration
        application:
          description: Application export data
          allOf:
            - $ref: '#/components/schemas/IdoExportDataResponseDto'
        external_connections_and_typed_lists:
          description: >-
            External connections and typed lists referenced by the export. These
            references are not exported secrets and must resolve to existing
            resources in the target tenant
          type: array
          items:
            $ref: '#/components/schemas/IdoExportDataResponseDto'
        keys_alias:
          description: >-
            List of key aliases referenced by the export. These keys must
            already exist in the target tenant before import
          allOf:
            - $ref: '#/components/schemas/IdentityData'
        credentials_alias:
          description: >-
            List of credential aliases referenced by the export. These
            credentials must already exist in the target tenant before import
          allOf:
            - $ref: '#/components/schemas/IdentityData'
        certificates_alias:
          description: >-
            List of certificate aliases referenced by the export. These
            certificates must already exist in the target tenant before import
          allOf:
            - $ref: '#/components/schemas/IdentityData'
        environment_variables_alias:
          description: >-
            List of environment variable aliases referenced by the export. These
            environment variables must already exist in the target tenant before
            import
          type: array
          items:
            type: string
      required:
        - version
        - application
        - external_connections_and_typed_lists
        - keys_alias
        - credentials_alias
        - certificates_alias
        - environment_variables_alias
    ImportUnifiedResponseDto:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
            - failure
            - not applicable
          description: Overall status of the import process
        details:
          type: string
          enum:
            - Import completed successfully
            - Force import completed successfully
            - Import failed
            - Force import failed
            - Import body is empty
            - Not applicable
          description: Detailed import result
      required:
        - status
        - details
    ValidationError:
      type: object
      properties:
        type:
          type: string
          enum:
            - VERSION_MISMATCH
            - MISSING_CREDENTIALS
            - MISSING_CERTIFICATES
            - MISSING_KEYS
            - MISSING_ENVIRONMENT_VARIABLES
            - EMPTY_EXPORT_DATA
            - INVALID_IDO_STRUCTURE
            - ZIP_FILE_SIZE_LIMIT_EXCEEDED
            - INVALID_AUTHENTICATION_AND_USER_MANAGEMENT_INPUT
          description: Type of validation error
        message:
          type: string
          description: Error message
        details:
          description: Error details
          type: array
          items:
            type: string
      required:
        - type
        - message
        - details
    ValidationUnifiedResponseDto:
      type: object
      properties:
        isValid:
          type: boolean
          description: Indicates if the validation was successful
        errors:
          description: List of validation errors
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      required:
        - isValid
        - errors
