openapi: '3.0.3'
info:
  title: Agent Management API
  description: >
    API defining resources and operations for managing agents.

    
    Generating a Boarding Configuration action is an asynchronous operation
    therefore it may take a while. 
    
    In case Boarding Configuration is not generated, try to read the configuration again after a couple of seconds.
  
  version: '3.6.0'
  x-visibility: external

servers:
  - url: https://api.eu1.siemens.app/agentmanagement-1000001700/v3
    description: Xcelerator compliant URL

tags:
  - name: Agent Operations
  - name: Data Source Configuration Operations
  - name: Boarding Operations
  - name: Registration Operations
  - name: Token Operations

paths:
  /agents:
    post:
      tags:
        - Agent Operations
      summary: Create agent
      description: |
        Creates a new agent.
      security:
        - agents:
            - agm.c
      requestBody:
        description: Object describing new agent resource.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '409':
          description: Resource is already available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
    get:
      tags:
        - Agent Operations
      summary: Get agents
      description: |
        Gets the agents for the given filter.
      security:
        - agents:
            - agm.r
      parameters:
        - name: filter
          in: query
          description: |
              JSON based filter.
              Filter json can contain following fields:
              * securityProfile (Agents securityProfiles can be "RSA_3072", "SHARED_SECRET")
              E.g.: {"securityProfile":"SHARED_SECRET"}
              * id
              E.g.: {"id":"3b27818ea09a46b48c7eb3fbd878349f"}
              * name
              E.g.: {"name":"Nanobox Agent"}
          required: false
          schema:
            type: string
        - name: size
          in: query
          description: The maximum number of elements in a page.
          required: false
          schema:
            type: integer
            default: 20
            format: int32
        - name: page
          in: query
          description: The (0-based) index of page.
          required: false
          schema:
            type: integer
            default: 0
            format: int32
        - name: sort
          in: query
          description: |
            The order of returned elements.
            Multiple fields could be used separated by commas (e.g. ''field1,field2'').
            Descending order could be requested by appending '',desc'' at the end of parameter.(e.g. ''field1,field2,desc'')'
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Array of agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAgent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
  /agents/{id}:
    get:
      tags:
        - Agent Operations
      summary: Get agent
      description: |
        Gets the agent for the given agent id.
      security:
        - agents:
            - agm.r
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
    put:
      tags:
        - Agent Operations
      summary: Update agent
      description: |
        Updates the agent for the given agent id with given parameters.
      security:
        - agents:
            - agm.u
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
        - in: header
          name: If-Match
          description: ETag number of resource.
          required: true
          schema:
            type: string
      requestBody:
        description: Agent update dto to update agent.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '409':
          description: Resource is already available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preconditionfailed'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
    delete:
      tags:
        - Agent Operations
      summary: Delete agent
      description: |
        Deletes the agent for the given agent id.
      security:
        - agents:
            - agm.d
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
        - in: header
          name: If-Match
          description: ETag number of resource.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preconditionfailed'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
  /agents/{id}/status:
    get:
      tags:
        - Agent Operations
      summary: Get online status
      description: |
        Gets online status.
      security:
        - agents:
            - agm.r
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnlineStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.

  /agents/{id}/boarding/configuration:
    get:
      tags:
        - Boarding Operations
      summary: Get boarding configuration
      description: |
        Boarding configuration holds necessary information of the agent to onboard it.(ex; iat, clientCredentialProfile). Generating a Boarding Configuration action is an asynchronous operation therefore it may take a few seconds. In case Boarding Configuration is not generated, try to read the configuration again after a couple of seconds.
      security:
        - boarding:
            - obc.sec
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
  /agents/{id}/boarding/offboard:
    post:
      tags:
        - Boarding Operations
      summary: Offboard agent
      description: |
        Offboards the agent.
      security:
        - boarding:
            - obc.sec
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '409':
          description: Resource in conflicting state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
        '422':
          description: Not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotSupported'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
  /agents/{id}/boarding/status:
    get:
      tags:
        - Boarding Operations
      summary: Get boarding status
      description: |
        Gets boarding status.
      security:
        - boarding:
            - obc.r
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.

  /agents/{id}/dataSourceConfiguration:
    get:
      tags:
        - Data Source Configuration Operations
      summary: Get Data Source Configuration
      description: |
        Data source configuration is needed for interpreting the data received from an agent. It is crucial for Mindsphere to interpret the data sent by an agent. The data source configuration contains data sources and data points. Data sources are logical groups of data points, e.g. a sensor or a machine. Fetches data source configuration object.
      security:
        - dataSources:
            - dsc.r
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceConfiguration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
    put:
      tags:
        - Data Source Configuration Operations
      summary: Update Data Source Configuration
      description: |
        Creates or updates data source configuration object.
      security:
        - dataSources:
            - dsc.u
      parameters:
        - name: id
          in: path
          description: Unique identifier of the agent.
          required: true
          schema:
            type: string
        - in: header
          name: If-Match
          description: ETag number of resource.
          required: true
          schema:
            type: string
      requestBody:
        description: Data source configuration object.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataSourceConfigurationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceConfiguration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badrequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notfound'
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preconditionfailed'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.

  /register:
    post:
      tags:
        - Registration Operations
      summary: Register client.
      description: |
        Registers client based on given security profile.
      parameters:
        - name: Authorization
          in: header
          description: Initial Access Token value with Bearer authentication scheme.
            e.g :Bearer eyJh...
          required: true
          schema:
            type: string
      requestBody:
        description: The client's key in JWKS for security profile RSA.
          If security profile is SHARED_SECRET the value is empty JSON.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Keys'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientIdentifier'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadrequestIAM'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedIAM'
        '429':
          description: TooManyRequests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Other error with any status code and response body format.
  /register/{client_id}:
    put:
      tags:
        - Registration Operations
      summary: Update client information.
      description: |
        Updates clients information.
      parameters:
        - name: Authorization
          in: header
          description: Registration Access Token value with Bearer authentication scheme.
            e.g :Bearer eyJh...
          required: true
          schema:
            type: string
        - name: client_id
          in: path
          description: Client identifier to update information.
          required: true
          schema:
            type: string
      requestBody:
        description: The client's key in JWKS for security profile RSA.
          If security profile is SHARED_SECRET there is only client_id in the JSON.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RotationKeys'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientIdentifier'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadrequestIAM'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedIAM'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.

  /oauth/token:
    post:
      tags:
        - Token Operations
      summary: Grant an Access Token
      description: |
        Grants an Access Token.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_assertion_type
                - client_assertion
              properties:
                grant_type:
                  type: string
                  description: The type of authentication being used to obtain the token, only  client_credentials is supported.
                client_assertion_type:
                  type: string
                  description: Defines the assertion type, only urn:ietf:params:oauth:client-assertion-type:jwt-bearer is supported.
                client_assertion:
                  type: string
                  description: |
                    A jwt which is signed with client secret
                    
                    Signing keys (client secret) can vary depending on agent security profile:<br>
                        - __SHARED_SECRET__: Client secret is provided by '/register' | '/register/<client_id>' endpoint
                        - __RSA_3072__: Private part of the client's RSA key which the public part was provided at '/register' | '/register/<client_id>'
                        - __CACertifiedX509__: Private counterpart of device certificate's public key.
      responses:
        '200':
          description: OK
          headers:
            Server-Time:
              description: Server time represented as epoch(unix) time in seconds.
              schema:
                type: integer
                format: int64
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          description: Bad Request
          headers:
            Server-Time:
              description: Server time represented as epoch(unix) time in seconds.
              schema:
                type: integer
                format: int64
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadrequestIAM'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
  /oauth/token_key:
    get:
      tags:
        - Token Operations
      summary: Returns the JWT signing key currently employed by Agent IAM
      description: |
        Provides current RSA public key of AgentIAM. AgentIAM uses corresponding RSA private key to sign access tokens, RATs and IATs.
      parameters:
        - name: If-None-Match
          in: header
          description: If-None-Match Parameter.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenKey'
        '304':
          description: Not Modified
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.
  /oauth/token_keys:
    get:
      tags:
        - Token Operations
      summary: Returns the JWT signing keys currently and previously employed by Agent IAM
      description: |
        Returns all valid JWT signing keys which can be used to verify JWTs (Bearer, RAT, IAT) issued by AgentIAM.
        The first key corresponds to the currently employed one, all others have been used in the past.
        The "kid" JWT claim allows to identify the signing key to be used.
        This endpoint conforms with RFC 7517 and RFC 7518 and endpoints output can be parsed as stated in the above mentioned RFCs.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenKeys'
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitExceeded'
        default:
          description: Other error with any status code and response body format.

components:

  schemas:
    CreateAgentRequest:
      type: object
      required:
            - name
            - securityProfile
            - entityId
      properties:
          name:
            type: string
            maxLength: 128
            example: 'Nanobox Agent'
            description: Name must be unique per tenant.
          securityProfile:
            type: string
            enum:
            - SHARED_SECRET
            - RSA_3072
          entityId:
              type: string
              description: Unique identifier of the entity
              maxLength: 36
              example: '3b27818ea09a46b48c7eb3fbd878349f'

    Agent:
      type: object
      required:
          - name
          - securityProfile
          - entityId
      properties:
          name:
            type: string
            maxLength: 128
            example: 'Nanobox Agent'
            description: Name must be unique per tenant.
          securityProfile:
            type: string
            enum:
            - SHARED_SECRET
            - RSA_3072
            - NATIVE_CA_CERTIFIED_X509
          id:
            type: string
            description: Unique identifier of the agent
            maxLength: 36
            example: '3b27818ea09a46b48c7eb3fbd878349f'
          eTag:
            type: string
            example: '2'
          entityId:
            type: string
            description: Unique identifier of the entity
            maxLength: 36
            example: '3b27818ea09a46b48c7eb3fbd878349f'

    PagedAgent:
      type: object
      required:
        - content
        - totalPages
        - totalElements
        - last
        - numberOfElements
        - first
        - sort
        - size
        - number
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
        last:
          description: Whether the current item is the last one.
          type: boolean
          example: true
        totalPages:
          description: The number of total pages.
          type: integer
          example: 1
        totalElements:
          description: The total amount of elements.
          type: integer
          example: 1
        numberOfElements:
          description: The number of elements currently on this page.
          type: integer
          example: 1
        first:
          description: Whether the current item is the first one.
          type: boolean
          example: true
        sort:
          description: The sorting parameters for the page.
          type: array
          items:
            $ref: '#/components/schemas/Order'
          example: null
        size:
          description: The size of the page.
          type: integer
          example: 20
        number:
          description: The number of the current item.
          type: integer
          example: 0

    Order:
      type: object
      properties:
        direction:
          description: The order the property shall be sorted for.
          type: string
          enum:
            - ASC
            - DESC
        property:
          description: The property to order for.
          type: string
        ignoreCase:
          description: Whether or not the sort will be case sensitive.
          type: boolean
        nullHandling:
          type: string
          enum:
            - NATIVE
            - NULLS_FIRST
            - NULLS_LAST
        descending:
          description: Whether sorting for this property shall be descending.
          type: boolean
        ascending:
          description: Whether sorting for this property shall be ascending.
          type: boolean

    UpdateAgentRequest:
      type: object
      required:
        - name
        - securityProfile
      properties:
        name:
          type: string
          maxLength: 128
          example: 'Nanobox Agent'
          description: Name must be unique per tenant.
        securityProfile:
          type: string
          enum:
            - SHARED_SECRET
            - RSA_3072

    OnlineStatus:
      type: object
      properties:
        status:
          type: string
          enum:
            - ONLINE
            - OFFLINE
        since:
          type: string
          format: date-time

    UpdateDataSourceConfigurationRequest:
      type: object
      required:
        - configurationId
        - dataSources
      properties:
        configurationId:
          type: string
          maxLength: 36
          description: Unique identifier of the datasource configuration.
          example: "Configuration01"
        dataSources:
          type: array
          items:
            $ref: '#/components/schemas/DataSource'

    DataSourceConfiguration:
      type: object
      required:
        - configurationId
        - dataSources
      properties:
        id:
          type: string
          maxLength: 36
          example: "c3b7d31d-e966-46e6-9db1-d4b3e8c90d7b"
        eTag:
          type: string
          example: '2'
        configurationId:
          type: string
          maxLength: 36
          description: Unique identifier of the datasource configuration.
          example: "Configuration01"
        dataSources:
          type: array
          items:
            $ref: '#/components/schemas/DataSource'

    DataSource:
      type: object
      required:
        - name
        - dataPoints
      properties:
        name:
          type: string
          maxLength: 64
          example: "OPC-UA Server"
        description:
          type: string
          maxLength: 256
          example: "OPC-UA Server installed on site."
        dataPoints:
          type: array
          items:
            $ref: '#/components/schemas/DataPoint'
        customData:
          type: object
          additionalProperties: {}
          description: A custom object of user-defined attributes.
          example:
            Host: "192.168.0.111"
            Port: "8765"
            details:
              tag: "Server-1"

    DataPoint:
      type: object
      required:
        - id
        - name
        - type
        - unit
      properties:
        id:
          type: string
          maxLength: 36
          description: |
            Identifier of this data point. This id needs to be unique per data source configuration. Agents expected to upload timeseries value with this id, enabling backend services to match data with this data point. 
            This is NOT an auto generated field, enabling agents to specify it before uploading matching timeseries value.
          example: DP001
        name:
          type: string
          maxLength: 64
          example: "Voltage"
        description:
          type: string
          maxLength: 256
          example: "Voltage value read."
        type:
          type: string
          enum:
            - INT
            - LONG
            - DOUBLE
            - BOOLEAN
            - STRING
          example: DOUBLE
        unit:
          type: string
          maxLength: 32
          description: |
            Unit of data point. Can be empty.
          example: V
        customData:
          type: object
          additionalProperties: {}
          description: A custom object of user-defined attributes.
          example:
            Nominal: "~220 Volts"
            details:
              tag: "Machine-1"

    Configuration:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/OnboardingConfigurationContent'
        expiration:
          type: string
          format: date-time

    OnboardingConfigurationContent:
      type: object
      properties:
        baseUrl:
          type: string
          example: 'https://southgate.eu-central.mindsphere.io'
        iat:
          type: string
          example: 'eyJh...'
        clientCredentialProfile:
          type: array
          items:
            type: string
            enum:
              - SHARED_SECRET
              - RSA_3072
              - NATIVE_CA_CERTIFIED_X509
        clientId:
          type: string
          example: '5fa51b64-dce2-11e7-9296-cec278b6b50a'
          maxLength: 36
        tenant:
          type: string
          example: 'testtenant'
          maxLength: 36

    OnboardingStatus:
      type: object
      properties:
        status:
          type: string
          enum:
            - NOT_ONBOARDED
            - ONBOARDING
            - ONBOARDED

    Keys:
      type: object
      properties:
        jwks:
          $ref: '#/components/schemas/Jwks'

    RotationKeys:
      type: object
      properties:
        client_id:
          type: string
        jwks:
          $ref: '#/components/schemas/Jwks'

    Jwks:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/Key'

    Key:
      type: object
      required: [e, n, kty, kid]
      properties:
        e:
          type: string
        n:
          type: string
        kty:
          type: string
          example: 'RSA'
        kid:
          type: string

    ClientIdentifier:
      type: object
      required: [client_id, registration_client_uri, registration_access_token]
      properties:
        client_id:
          $ref: '#/components/schemas/ClientId'
        client_secret:
          type: string
          description: Server generated client secret. Required if security profile is SHARED_SECRET.
        client_secret_expires_at:
          type: integer
          format: int64
          description: Epoch time in seconds which client secret expires at.
          example: 1511020133
        grant_types:
          type: array
          items:
            type: string
            enum:
              - SHARED_SECRET
              - RSA_3072
              - NATIVE_CA_CERTIFIED_X509
        registration_access_token:
          type: string
          description: The access token to be used at the client configuration endpoint to perform subsequent operations upon the client registration.
          example: 'eyJh...'
        registration_client_uri:
          type: string
          description: The fully qualified URL of the client configuration endpoint for this client.
          format: uri
          example: 'https://southgate.eu-central.mindsphere.io/api/agentmanagement/v3/register/0b2d1cde-cc76-11e7-abc4-cec278b6b50a'
        token_endpoint_auth_method:
          type: string
          description: The client authentication method.
          enum:
            - client_secret_jwt
            - private_key_jwt

    ClientId:
      type: string
      description: Client identifier, equals value of 'sub' claim in IAT.
      maxLength: 36
      example: '0b2d1cde-cc76-11e7-abc4-cec278b6b50a'

    Jti:
      type: string
      description: Unique identifier of the token.
      maxLength: 36
      example: '3fcf2a5e-cc76-11e7-abc4-cec278b6b50a'

    AccessToken:
      type: object
      properties:
        access_token:
          type: string
          description: The access token to be used in calls to MindSphere with Bearer authentication scheme.
          example: 'eyJh...'
        token_type:
          type: string
          description: The type of the access token issued.
          example: 'bearer'
        expires_in:
          type: integer
          description: Number of seconds before this token expires from the time of issuance.
          format: int64
          example: 43199
        jti:
          $ref: '#/components/schemas/Jti'
        scope:
          description: Agent permissions list.
          type: array
          items:
            type: string
            example: 'devicescope'

    TokenKey:
      type: object
      required: [e, n, kty, kid]
      properties:
        alg:
          type: string
        use:
          type: string
        value:
          type: string
        e:
          type: string
        n:
          type: string
        kty:
          type: string
          example: 'RSA'
        kid:
          type: string
    TokenKeys:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/TokenKey'

    Unauthorized:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
          example: 'Not authorized to access this resource.'

    Forbidden:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
          example: 'Insufficient authorization for this resource.'

    Badrequest:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
          example: 'The request is not valid.'

    Notfound:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
          example: 'Resource not found.'

    Conflict:
      type: object
      description: Operation on resource is not allowed due to a conflicting state.
      properties:
        id:
          type: string
        message:
          type: string
          example: 'Resource is already available.'

    NotSupported:
      type: object
      description: Operation on resource is not allowed for NATIVE_CA_CERTIFIED_X509 agents.
      properties:
        id:
          type: string
        message:
          type: string
          example: 'Offboard request is not supported for NATIVE_CA_CERTIFIED_X509 agents.'

    Preconditionfailed:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
          example: 'Resource not found with given the condition.'

    Error:
      type: object
      properties:
        id:
          type: string
        message:
          type: string

    BadrequestIAM:
      type: object
      properties:
        id:
          type: string
        error:
          type: string
          example: 'invalid_authorization_header'
        error_description:
          type: string
          description: An error message with Correlation-ID value.
          example: '[feae1a0b-48fb-4af5-bc0d-7c96d8058e37] Header is missing.'

    UnauthorizedIAM:
      type: object
      properties:
        id:
          type: string
        error:
          type: string
          example: 'token_validation_failed'
        error_description:
          type: string
          description: An error message with Correlation-ID value.
          example: '[d6270fa4-f8f2-46d7-8370-1fbcacb37c52] Token validation failed.'

    TooManyRequests:
      type: object
      properties:
        id:
          type: string
        error:
          type: string
          example: 'too_many_requests'
        error_description:
          type: string
          description: An error message with Correlation-ID value.
          example: '[d6270fa4-f8f2-46d7-8370-1fbcacb37c52] There is already an ongoing registration process for the agent.'

    APIRateLimitExceeded:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
          example: 'API rate limit exceeded.'

  securitySchemes:
    agents:
      type: oauth2
      description: |
        For **Xcelerator** compliance, please use **authorizationUrl** = https://1000001700.eu1.sws.siemens.com/oauth/authorize and **tokenUrl** = https://1000001700.eu1.sws.siemens.com/oauth/token
      flows:
        authorizationCode:
          authorizationUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/authorize'
          tokenUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/token'
          scopes:
            agm.c: Permission to create an agent.
            agm.r: Permission to read an agent.
            agm.u: Permission to update agent.
            agm.d: Permission to delete agent.
    boarding:
      type: oauth2
      description: |
        For **Xcelerator** compliance, please use **authorizationUrl** = https://1000001700.eu1.sws.siemens.com/oauth/authorize and **tokenUrl** = https://1000001700.eu1.sws.siemens.com/oauth/token
      flows:
        authorizationCode:
          authorizationUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/authorize'
          tokenUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/token'
          scopes:
            obc.r: Permission read onboarding status.
            obc.sec: Permission for offboarding and accessing onboarding material.
    dataSources:
      type: oauth2
      description: |
        For **Xcelerator** compliance, please use **authorizationUrl** = https://1000001700.eu1.sws.siemens.com/oauth/authorize and **tokenUrl** = https://1000001700.eu1.sws.siemens.com/oauth/token
      flows:
        authorizationCode:
          authorizationUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/authorize'
          tokenUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/token'
          scopes:
            dsc.r: Permission to read data source configuration
            dsc.u: Permission to update data source configuration
