swagger: "2.0"
info:
  version: "4.4.1"
  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"
basePath: "/api/tenantmanagement/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"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      responses:
        "200":
          description: "OK"
          schema:
            $ref: "#/definitions/PageSubtenantResource"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
      security:
        - accessCode:
            - "tm.st.r"
    post:
      tags:
        - "subtenant"
      summary: "Create a subtenant"
      operationId: "createSubtenant"
      consumes:
        - "application/json"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - in: "body"
          name: "subtenant"
          description: "subtenant"
          required: true
          schema:
            $ref: "#/definitions/Subtenant"
      responses:
        "201":
          description: "Created"
          schema:
            $ref: "#/definitions/SubtenantResource"
          headers:
            Location:
              type: "string"
              description: "URL of the resource"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "409":
          description: "Conflict"
        "500":
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/MdspErrors"
      security:
        - accessCode:
            - "tm.st.c"
  /subtenants/{id}:
    get:
      tags:
        - "subtenant"
      summary: "Get a subtenant by id"
      operationId: "retrieveSubtenant"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - name: "id"
          in: "path"
          description: "id"
          required: true
          type: "string"
      responses:
        "200":
          description: "OK"
          schema:
            $ref: "#/definitions/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"
      consumes:
        - "application/json"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - name: "id"
          in: "path"
          description: "id"
          required: true
          type: "string"
        - in: "body"
          name: "subtenantUpdateProperties"
          description: "subtenantUpdateProperties"
          required: true
          schema:
            $ref: "#/definitions/SubtenantUpdateProperties"
        - name: "If-Match"
          in: "header"
          description: "If-Match"
          required: true
          type: "string"
      responses:
        "200":
          description: "OK"
          schema:
            $ref: "#/definitions/SubtenantResource"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
        "412":
          description: "Precondition failed"
          schema:
            $ref: "#/definitions/MdspErrors"
        "500":
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/MdspErrors"
      security:
        - accessCode:
            - "tm.st.u"
    delete:
      tags:
        - "subtenant"
      summary: "Delete a subtenant by id"
      operationId: "deleteSubtenant"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - name: "id"
          in: "path"
          description: "id"
          required: true
          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"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      responses:
        "200":
          description: "Ok"
          schema:
            $ref: "#/definitions/LegalConfiguration"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
          schema:
            $ref: "#/definitions/LegalConfiguration"
      security:
        - accessCode:
            - "tm.li.r"
    post:
      tags:
        - "legal"
      summary: "Creates tenant legal information"
      operationId: "createLegalConfiguration"
      consumes:
        - "application/json"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - in: "body"
          name: "legalConfiguration"
          description: "legalConfiguration"
          required: true
          schema:
            $ref: "#/definitions/LegalConfiguration"
      responses:
        "201":
          description: "Created"
          schema:
            $ref: "#/definitions/LegalConfigurationResource"
          headers:
            Location:
              type: "string"
              description: "URL of the resource"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/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"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      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"
      consumes:
        - "application/json"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - name: "regionId"
          in: "path"
          description: "regionId"
          required: true
          type: "string"
        - in: "body"
          name: "region"
          description: "region"
          required: true
          schema:
            $ref: "#/definitions/Region"
        - name: "If-Match"
          in: "header"
          description: "If-Match"
          required: true
          type: "string"
      responses:
        "200":
          description: "Ok"
          schema:
            $ref: "#/definitions/RegionResource"
        "204":
          description: "No Content"
          schema:
            $ref: "#/definitions/RegionResource"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "409":
          description: "Conflict"
          schema:
            $ref: "#/definitions/ErrorResponse"
      security:
        - accessCode:
            - "tm.li.u"
    delete:
      tags:
        - "legal"
      summary: "Delete legal information configuration of a region"
      operationId: "deleteRegion"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - name: "regionId"
          in: "path"
          description: "regionId"
          required: true
          type: "string"
        - name: "If-Match"
          in: "header"
          description: "If-Match"
          required: true
          type: "string"
      responses:
        "204":
          description: "No content"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/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"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      responses:
        "200":
          description: "Ok"
          schema:
            $ref: "#/definitions/LegalConfiguration"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
          schema:
            $ref: "#/definitions/LegalConfiguration"
  /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"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - name: "tenantId"
          in: "path"
          description: "tenantId"
          required: true
          type: "string"
      responses:
        "200":
          description: "Ok"
          schema:
            $ref: "#/definitions/LegalConfiguration"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
          schema:
            $ref: "#/definitions/LegalConfiguration"
  /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"
      produces:
      - "application/json"
      - "application/hal+json (deprecated)"
      parameters:
        - name: "tenantId"
          in: "path"
          description: "tenantId"
          required: true
          type: "string"
      responses:
        "200":
          description: "Ok"
          schema:
            $ref: "#/definitions/LegalConfiguration"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
          schema:
            $ref: "#/definitions/LegalConfiguration"
  /tenantInfo:
    get:
      tags:
        - "tenant info"
      summary: "Get tenant info"
      description: "Without scope protection"
      operationId: "queryTenantInfo"
      produces:
        - "application/json"
      responses:
        "200":
          description: "OK"
          schema:
            $ref: "#/definitions/TenantInfo"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
    patch:
      tags:
        - "tenant info"
      summary: "Patch tenant info"
      operationId: "patchTenantInfo"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "tenantInfoUpdateProperties"
          description: "tenantInfoUpdateProperties"
          required: true
          schema:
            $ref: "#/definitions/TenantInfoUpdateProperties"
        - name: "If-Match"
          in: "header"
          description: "If-Match"
          required: true
          type: "string"
      responses:
        "200":
          description: "OK"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
      security:
      - accessCode:
        - "mdspiam.tenantadmin"
  /tenantInfo/logo:
    get:
      tags:
        - "tenant info"
      summary: "Get tenant logo"
      description: "Without scope protection"
      operationId: "queryLogo"
      produces:
        - "image/png"
        - "image/gif"
        - "image/jpeg"
      responses:
        "200":
          description: "Ok"
          schema:
            type: "file"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
    post:
      tags:
        - "tenant info"
      summary: "Upload tenant logo"
      operationId: "createLogo"
      consumes:
        - "multipart/form-data"
      produces:
        - "application/json"
      parameters:
        - name: "file"
          in: "formData"
          description: "file"
          required: true
          type: "file"
      responses:
        "200":
          description: "OK"
          schema:
            $ref: "#/definitions/UploadedFileResource"
        "201":
          description: "Created"
          schema:
            $ref: "#/definitions/UploadedFileResource"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
      security:
      - accessCode:
        - "mdspiam.tenantadmin"
    delete:
      tags:
        - "tenant info"
      summary: "Delete tenant logo"
      operationId: "deleteLogo"
      produces:
        - "application/json"
      responses:
        "204":
          description: "No Content"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not Found"
      security:
      - accessCode:
        - "mdspiam.tenantadmin"
  /tenantInfo/logoMetaData:
    get:
      tags:
        - "tenant info"
      summary: "Get tenant logo metadata"
      description: "Without scope protection"
      operationId: "queryLogoMetaData"
      produces:
        - "application/json"
      responses:
        "200":
          description: "Ok"
          schema:
            $ref: "#/definitions/UploadedFileResource"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not found"
securityDefinitions:
  accessCode:
    type: "oauth2"
    authorizationUrl: "http://UAA_DOMAIN//oauth/token"
    tokenUrl: "http://UAA_DOMAIN/oauth/token"
    flow: "accessCode"
    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"
      mdspiam.tenantadmin: "Identifier scope of tenant administrator"
definitions:
  ErrorResponse:
    type: "object"
    properties:
      errorMessage:
        type: "string"
      errorType:
        type: "string"
        enum:
          - "FIELD_ERROR"
          - "UNEXPECTED_ERROR"
          - "INVALID_STATE"
          - "PARSING_ERROR"
      fieldErrors:
        type: "array"
        items:
          $ref: "#/definitions/FieldError"
      logref:
        type: "string"
    title: "ErrorResponse"
  FieldError:
    type: "object"
    properties:
      errorMessage:
        type: "string"
      errorType:
        type: "string"
        enum:
          - "INVALID_INPUT"
          - "VALIDATION_ERROR"
          - "NOT_ALLOWED"
          - "UNIQUE_CONSTRAINT_ERROR"
      field:
        type: "string"
    title: "FieldError"
  LegalConfiguration:
    type: "object"
    required:
      - "regions"
    properties:
      regions:
        type: "array"
        items:
          $ref: "#/definitions/Region"
    title: "LegalConfiguration"
  LegalConfigurationResource:
    type: "object"
    properties:
      regions:
        type: "array"
        items:
          $ref: "#/definitions/RegionResource"
    title: "LegalConfigurationResource"
  Link:
    type: "object"
    required:
      - "name"
      - "value"
    properties:
      name:
        type: "string"
      value:
        type: "string"
    title: "Link"
  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: "#/definitions/Link"
    title: "LinkCollection"
  MdspError:
    type: "object"
    properties:
      code:
        type: "string"
      logref:
        type: "string"
      message:
        type: "string"
    title: "MdspError"
  MdspErrors:
    type: "object"
    properties:
      errors:
        type: "array"
        items:
          $ref: "#/definitions/MdspError"
    title: "MdspErrors"
  PageSubtenantResource:
    type: "object"
    properties:
      content:
        type: "array"
        items:
          $ref: "#/definitions/SubtenantResource"
      first:
        type: "boolean"
      last:
        type: "boolean"
      number:
        type: "integer"
        format: "int32"
      numberOfElements:
        type: "integer"
        format: "int32"
      size:
        type: "integer"
        format: "int32"
      sort:
        $ref: "#/definitions/Sort"
      totalElements:
        type: "integer"
        format: "int64"
      totalPages:
        type: "integer"
        format: "int32"
    title: "PageSubtenantResource"
  Region:
    type: "object"
    required:
      - "regionName"
    properties:
      regionId:
        type: "string"
      regionName:
        type: "string"
        minLength: 1
        maxLength: 50
      regionCountries:
        type: "array"
        items:
          type: "string"
      links:
        type: "array"
        items:
          $ref: "#/definitions/LinkCollection"
    title: "Region"
  RegionResource:
    type: "object"
    properties:
      ETag:
        type: "integer"
        format: "int64"
      links:
        type: "array"
        items:
          $ref: "#/definitions/LinkCollection"
      regionCountries:
        type: "array"
        items:
          type: "string"
      regionId:
        type: "string"
      regionName:
        type: "string"
    title: "RegionResource"
  Sort:
    type: "object"
    title: "Sort"
    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."
    title: "Subtenant"
  SubtenantResource:
    type: "object"
    properties:
      ETag:
        type: "integer"
        format: "int64"
      description:
        type: "string"
      displayName:
        type: "string"
      entityId:
        type: "string"
      id:
        type: "string"
    title: "SubtenantResource"
  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"
    title: "SubtenantUpdateProperties"
  TenantInfo:
    type: "object"
    properties:
      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:
          - "DEVELOPER"
          - "OPERATOR"
          - "USER"
          - "CUSTOMER"
    title: "TenantInfo"
  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"
    title: "TenantInfoUpdateProperties"
  UploadedFileResource:
    type: "object"
    properties:
      size:
        type: "integer"
        format: "int64"
      name:
        type: "string"
    title: "UploadedFileResource"
