openapi: 3.0.1
info:
  version: "3.17.0"
  title: Tenant Management API
  description: |
    The Tenant Management API provides endpoints for managing subtenants, and the legal configuration and the basic properties of tenants.
  x-visibility: external
servers:
  - url: https://api.eu1.siemens.app/tenantmanagement-1000001700/v4
tags:
  - name: legal
    description: Legal Endpoints
  - name: tenant info
    description: Tenant Info Endpoints
  - name: subtenant
    description: Subtenant Endpoints
paths:
  /subtenants:
    get:
      tags:
        - subtenant
      summary: Get subtenants
      operationId: querySubtenants
      parameters:
        - name: page
          in: query
          description: Specifies the requested page index
          schema:
            type: integer
        - name: size
          in: query
          description: Specifies the number of elements in a page
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageSubtenantResource'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - accessCode:
            - tm.st.r
    post:
      tags:
        - subtenant
      summary: Create a subtenant
      operationId: createSubtenant
      requestBody:
        description: subtenant
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subtenant'
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema:
                type: string
              description: URL of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubtenantResource'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: Conflict
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MdspErrors'
      security:
        - accessCode:
            - tm.st.c
  /subtenants/{id}:
    get:
      tags:
        - subtenant
      summary: Get a subtenant by id
      operationId: retrieveSubtenant
      parameters:
        - name: id
          in: path
          description: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubtenantResource'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
      security:
        - accessCode:
            - tm.st.r
    put:
      tags:
        - subtenant
      summary: Update a subtenant by id
      operationId: updateSubtenant
      parameters:
        - name: id
          in: path
          description: id
          required: true
          schema:
            type: string
        - name: If-Match
          in: header
          description: If-Match
          required: true
          schema:
            type: string
      requestBody:
        description: subtenantUpdateProperties
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubtenantUpdateProperties'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubtenantResource'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '412':
          description: Precondition failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MdspErrors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MdspErrors'
      security:
        - accessCode:
            - tm.st.u
    delete:
      tags:
        - subtenant
      summary: Delete a subtenant by id
      operationId: deleteSubtenant
      parameters:
        - name: id
          in: path
          description: id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
      security:
        - accessCode:
            - tm.st.d
  /legalConfigRegions:
    get:
      tags:
        - legal
      summary: Get the complete legal information configuration of current tenant
      operationId: queryLegalConfiguration
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalConfiguration'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
      security:
        - accessCode:
            - tm.li.r
    post:
      tags:
        - legal
      summary: Creates tenant legal information
      operationId: createLegalConfiguration
      requestBody:
        description: legalConfiguration
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalConfiguration'
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema:
                type: string
              description: URL of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalConfigurationResource'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: Conflict
      security:
        - accessCode:
            - tm.li.c
    delete:
      tags:
        - legal
      summary: Delete the complete legal information configuration of current tenant
      operationId: deleteLegalConfiguration
      responses:
        '204':
          description: No content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - accessCode:
            - tm.li.d
  /legalConfigRegions/{regionId}:
    put:
      tags:
        - legal
      summary: Update a region configuration of current tenant
      operationId: updateLegalConfiguration
      parameters:
        - name: regionId
          in: path
          description: regionId
          required: true
          schema:
            type: string
        - name: If-Match
          in: header
          description: If-Match
          required: true
          schema:
            type: string
      requestBody:
        description: region
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Region'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionResource'
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionResource'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - accessCode:
            - tm.li.u
    delete:
      tags:
        - legal
      summary: Delete legal information configuration of a region
      operationId: deleteRegion
      parameters:
        - name: regionId
          in: path
          description: regionId
          required: true
          schema:
            type: string
        - name: If-Match
          in: header
          description: If-Match
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
      security:
        - accessCode:
            - tm.li.d
  /legalInfo:
    get:
      tags:
        - legal
      summary: Get specific legal information
      description: Without scope protection
      operationId: retrieveSpecificLegalInformation
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalInformation'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
  /legalInfo/{tenantId}:
    get:
      tags:
        - legal
      summary: Get the region specific legal information for a given tenant with fallback logic to core tenant
      description: Without scope protection
      operationId: retrieveTenantLegalInfo
      parameters:
        - name: tenantId
          in: path
          description: tenantId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalInformation'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
  /legalInfoForSpecificTenant/{tenantId}:
    get:
      tags:
        - legal
      summary: Get the region specific legal information for a given tenant without fallback logic
      description: Without scope protection
      operationId: retrieveLegalConfigurationWithoutFallback
      parameters:
        - name: tenantId
          in: path
          description: tenantId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalInformation'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
  /tenantInfo:
    get:
      tags:
        - tenant info
      summary: Get tenant info
      description: Without scope protection
      operationId: queryTenantInfo
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantInfo'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
    patch:
      tags:
        - tenant info
      summary: Patch tenant info
      operationId: patchTenantInfo
      parameters:
        - name: If-Match
          in: header
          description: If-Match
          required: true
          schema:
            type: string
      requestBody:
        description: tenantInfoUpdateProperties
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantInfoUpdateProperties'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - accessCode:
            - tm.logo.w
  /tenantInfo/logo:
    get:
      tags:
        - tenant info
      summary: Get tenant logo
      description: Without scope protection
      operationId: queryLogo
      responses:
        '200':
          description: Ok
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/gif:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
    post:
      tags:
        - tenant info
      summary: Upload tenant logo
      operationId: createLogo
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: file
              required:
                - file
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedFileResource'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedFileResource'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - accessCode:
            - tm.logo.w
    delete:
      tags:
        - tenant info
      summary: Delete tenant logo
      operationId: deleteLogo
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
        - accessCode:
            - tm.logo.w
  /tenantInfo/logoMetaData:
    get:
      tags:
        - tenant info
      summary: Get tenant logo metadata
      description: Without scope protection
      operationId: queryLogoMetaData
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedFileResource'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorMessage:
          type: string
        errorType:
          type: string
          enum:
            - FIELD_ERROR
            - UNEXPECTED_ERROR
            - INVALID_STATE
            - PARSING_ERROR
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
        logref:
          type: string
    FieldError:
      type: object
      properties:
        errorMessage:
          type: string
        errorType:
          type: string
          enum:
            - INVALID_INPUT
            - VALIDATION_ERROR
            - NOT_ALLOWED
            - UNIQUE_CONSTRAINT_ERROR
        field:
          type: string
    LinkInfo:
      type: object
      required:
        - id
        - type
        - name
        - value
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
        value:
          type: string
    LegalInformation:
      type: object
      required:
        - legalLinks
      properties:
        legalLinks:
          description: Collection of legal links grouped by language
          type: object
          properties:
            default:
              type: array
              items:
                $ref: '#/components/schemas/LinkInfo'
            bs:
              type: array
              items:
                $ref: '#/components/schemas/LinkInfo'
            de:
              type: array
              items:
                $ref: '#/components/schemas/LinkInfo'
            en:
              type: array
              items:
                $ref: '#/components/schemas/LinkInfo'
    LegalConfiguration:
      type: object
      required:
        - regions
      properties:
        regions:
          type: array
          items:
            $ref: '#/components/schemas/Region'
    LegalConfigurationResource:
      type: object
      properties:
        regions:
          type: array
          items:
            $ref: '#/components/schemas/RegionResource'
    Link:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
        value:
          type: string
    LinkCollection:
      type: object
      required:
        - id
        - languages
        - type
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - www
            - phone
            - mail
        sorting:
          type: integer
          format: int32
        languages:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
    MdspError:
      type: object
      properties:
        code:
          type: string
        logref:
          type: string
        message:
          type: string
    MdspErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MdspError'
    PageSubtenantResource:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/SubtenantResource'
        first:
          type: boolean
        last:
          type: boolean
        number:
          type: integer
          format: int32
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        sort:
          $ref: '#/components/schemas/Sort'
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
    Region:
      type: object
      required:
        - regionName
      properties:
        regionId:
          type: string
        regionName:
          type: string
          minLength: 1
          maxLength: 50
        regionCountries:
          type: array
          items:
            type: string
        regionLinks:
          description: Collection of link configurations for this region
          type: array
          items:
            $ref: '#/components/schemas/LinkCollection'
    RegionResource:
      type: object
      properties:
        ETag:
          type: integer
          format: int64
        regionLinks:
          description: Collection of link configurations for this region
          type: array
          items:
            $ref: '#/components/schemas/LinkCollection'
        regionCountries:
          type: array
          items:
            type: string
        regionId:
          type: string
        regionName:
          type: string
    Sort:
      type: object
      properties:
        sorted:
          type: boolean
        unsorted:
          type: boolean
        empty:
          type: boolean
    Subtenant:
      type: object
      required:
        - description
        - displayName
        - id
      properties:
        id:
          type: string
          minLength: 2
          maxLength: 36
          pattern: "^[-_a-zA-Z0-9]*$"
          example: 19cb0bb8-0526-41a4-a95d-22368ba4a991
          description: A universally unique identifier.
        displayName:
          type: string
          minLength: 2
          maxLength: 50
          example: company ltd.
        description:
          type: string
          minLength: 2
          maxLength: 255
          example: This is a sample description.
    SubtenantResource:
      type: object
      properties:
        ETag:
          type: integer
          format: int64
        description:
          type: string
        displayName:
          type: string
        entityId:
          type: string
        id:
          type: string
    SubtenantUpdateProperties:
      type: object
      properties:
        displayName:
          type: string
          minLength: 2
          maxLength: 50
          example: Display name
        description:
          type: string
          minLength: 2
          maxLength: 255
          example: Car manufacturing company
    TenantInfo:
      type: object
      properties:
        id:
          type: string
          description: Unique tenant identifier. For IH-issued tokens this returns the IH tenant ID. For FDS-issued tokens this returns the FDS tenant ID.
        ETag:
          type: integer
          format: int64
        allowedToCreateSubtenant:
          type: boolean
        companyName:
          type: string
        country:
          type: string
        displayName:
          type: string
        name:
          type: string
        prefix:
          type: string
        type:
          type: string
          enum:
            - BASE
            - DEVELOPER
            - OPERATOR
            - FREE
            - USER
            - CUSTOMER
        siteId:
          type: string
          description: Site id received from SAP system.
        installNumber:
          type: string
          description: Installation number received from SAP system.
        isFree:
          type: boolean
          description: This value is set to true for free tenants.
          default: false
          example: false
        parentTenantId:
          type: string
          description: This is the Parent tenant's id.
          minLength: 2
          maxLength: 8
          pattern: "^[a-z][a-z0-9]*$"
          example: kuka
        whitelabeling:
          type: string
          description: Whitelabeling feature is used to enforce webkey to use customized email templates for user invitation emails.
          minLength: 0
          maxLength: 255
          example: mindsphere
    TenantInfoUpdateProperties:
      type: object
      properties:
        companyName:
          type: string
          minLength: 0
          maxLength: 255
          example: Company name
        displayName:
          type: string
          minLength: 2
          maxLength: 255
          example: Company display name
    UploadedFileResource:
      type: object
      properties:
        size:
          type: integer
          format: int64
        name:
          type: string
  securitySchemes:
    accessCode:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/authorize'
          tokenUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/token'
          scopes:
            tm.li.c: Create legal information
            tm.li.r: Read legal information
            tm.li.u: Update legal information
            tm.li.d: Delete legal information
            tm.st.c: Create subtenant
            tm.st.r: Get subtenant(s)
            tm.st.u: Update subtenant
            tm.st.d: Delete subtenant
            tm.logo.w: Modify tenant info or logo
