asyncapi: 2.2.0
info:
  version: 3.0.0
  x-visibility: internal
  title: Agent Management Async API
  description: >
    Agent Management Async API defines topics and message structures to request agent access token.


    Limitations:

    * There are frequency limits per tenant and per agent for published and
    received messages.

    * Maximum size of body is 128KBs.
servers:
  EU1:
    url: 'mindconnectmqtt.eu1.mindsphere.io:8883'
    description: |
      MQTT Broker for MindSphere which offers below described topics.
    protocol: mqtt
channels:
  'tc/{tenantId}/{clientId}/o/agm_v3/t':
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      description: Request agent access token.
      tags:
        - name: Token Request Operation
      message:
        summary: Token Request Message
        $ref: '#/components/messages/TokenRequestMessage'
  'tc/{tenantId}/{clientId}/i/agm_v3/tr':
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    subscribe:
      description: Receive result of a agent access token request.
      tags:
        - name: Token Request Operation
      message:
        summary: Token Request Result Message
        $ref: '#/components/messages/TokenRequestResultMessage'
components:
  messages:
    TokenRequestMessage:
      name: Token Request Message
      description: |
        Message contains access token request parameters.
      payload:
        $ref: '#/components/schemas/TokenRequestData'
    TokenRequestResultMessage:
      name: Token Request Result Message
      description: |
        Message contains result of a token request.
      payload:
        $ref: '#/components/schemas/TokenRequestResultData'
  schemas:
    TokenRequestData:
      title: TokenRequest
      type: object
      description: >-
      properties:
        id:
          type: string
          example: 72609761sdv245248e126814c283a27f
          description: Unique id of message.
          minLength: 1
          maxLength: 32
      required:
        - id
    TokenRequestResultData:
      title: TokenRequestResultData
      type: object
      properties:
        id:
          type: string
          example: 69149765fed2452c8e126814c283a27f
          description: Unique id of message.
          minLength: 1
          maxLength: 32
        requestId:
          type: string
          readOnly: true
          example: 72609761sdv245248e126814c283a27f
          description: Id of token request message that triggered access token generation. This field can only be undefined if the message that triggered token request was malformed (i.e. missing an id attribute).
          minLength: 1
          maxLength: 32
        data:
          type: object
          $ref: '#/components/schemas/AccessTokenResult'
      required:
        - id
        - data
    AccessTokenResult:
      title: AccessTokenResult
      type: object
      description: Structure containing access token.
      properties:
        access_token:
          type: string
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzaWVtZW5zX215bXF0dGRldmljZSIsIm5hbWUiOiJKb2huIERvZSIsImFkbWluIjp0cnVlLCJpYXQiOjE1MTYyMzkwMjIsInRlbmFudCI6InNpZW1lbnMiLCJyb2xlIjoiZGVmYXVsdEFnZW50Um9sZSJ9.YnvMhX1QdLuRKUJLtLXHluyARjAv67DTWuojGnuj2I1Qt7qM-Wi_FqfqfaedqMLP7b68gz7z2QU54HPd592T8IequIE-VOzMVKaeP7FbMWD7RZSBFVF7ZYiM8FXjFq2-5Qo9gOtpCMHlsStLSIUdeCkw4cFeXM9ziAtS5RSnuCI51bhH7w5ZO8betEj7eaQmmn80bQ364yMnE5pNiy43RptQzABp64D5xkldJimRK7ePdSFUslJWHdBBFy3xD0yubyu4FN0148fNSRJ3D1J3b2B7ugNWEVsv9N5U1J5ewxs63w9kiaKzhrMaDo-m0SoB5H-gn_1sni2sOb6AFDVnDQ
          description: >-
            The access token to be used in calls to MindSphere with Bearer authentication scheme.
          minLength: 1
          maxLength: 8096
        token_type:
          type: string
          enum:
            - Bearer
          example: Bearer
          description: >-
            The type of the access token issued.
        expires_in:
          type: integer
          example: 3600
          description: >-
            Number of seconds before this token expires from the time of issuance.
          format: int64
        scope:
          type: array
          minItems: 1
          maxItems: 100
          example: ["mdsp:core:DefaultAgent"]
          description: >-
            Agent permissions list.
          items:
            type: string
        jti:
          type: string
          format: uuid
          example: 931313fa-1a5f-42ae-b5b5-a896b5dfcabc
          description: >-
            Unique identifier of the token.
          minLength: 1
          maxLength: 36
        timestamp:
          type: number
          example: 1516239022
          description: Creation time of the access token in epoch format.
        errors:
          type: array
          minItems: 1
          maxItems: 100
          description: >-
            Error messages about access token request. It is only available in case of unsuccessful completion of the operation.
          items:
            $ref: '#/components/schemas/TokenRequestError'
          readOnly: false
    TokenRequestError:
      title: Token Request Error
      type: object
      description: Error response body.
      properties:
        code:
          type: string
          description: MindSphere error code
          example: mdsp.core.generic.missingRequestBodyProperty
        logref:
          type: string
          description: CorrelationId of message
          example: 01FZYX97V43CZXW6E5BAAYFAPT
        message:
          type: string
          description: Error message description
          example: >-
            Missing required request body property {id}
  parameters:
    ClientId:
      description: >-
        MQTT client id. See the MindSphere Developer Documentation overview page
        for this API to get more details.
      schema:
        type: string
        example: siemens_device001
    TenantId:
      description: >-
        Id of tenant which agent belongs to. See the MindSphere Developer
        Documentation overview page for this API to get more details.
      schema:
        type: string
        example: siemens
