openapi: 3.0.0
info:
  description: The API for Location Integration Module in the ThingPark X Platform
  version: 1.8.0
  title: Thingpark X Location Integration API
externalDocs:
  description: For more information, please check the online examples in this documentation.
  url: '/location-integration-module/latest/doc/index.html'
tags:
  - name: Tracker
    description: Operations for processing Trackers
  - name: Account
    description: Operations related to account information
  - name: Share
    description: Operations for sharing trackers
  - name: End user
    description: Operations related to end user
  - name: Realm
    description: Operations related to end user realm
  - name: App Version
    description: Operations related to mobile app version
paths:
  /trackerRegistration:
    post:
      tags:
        - Tracker
      summary: Add Tracker
      description: Register a tracker in the platform
      operationId: registerDevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceRegistrationInfo'
          application/xml:
            schema:
              $ref: '#/components/schemas/DeviceRegistrationInfo'
        required: true
      responses:
        '201':
          description: Successfully registered device
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
        '403':
          description: Registration Error - device association check failure
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /trackerRegistration/{deviceEUI}:
    delete:
      tags:
        - Tracker
      summary: Remove Tracker
      description: Delete a tracker from the platform
      operationId: removeDevice
      parameters:
        - name: deviceEUI
          in: path
          description: Device id to delete
          required: true
          schema:
            type: string
        - name: bleRemoveDownlink
          in: query
          description: send a downlink to device to remove ble bond
          required: false
          schema:
            type: boolean
            default: true
        - name: emailNotification
          in: query
          description: get notified by email if ble remove downlink is successful, default is false
          required: false
          schema:
            type: boolean
            default: false
        - name: interfaceNotification
          in: query
          description: get notified by push notification if ble remove downlink is successful, default is true
          required: false
          schema:
            type: boolean
            default: true
        - name: asyncResponseUplinkPeriods
          in: query
          description: Number of uplink periods to wait before notification timeout, range [0,5]
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 5
            default: 0
        - name: asyncResponseSlack
          in: query
          description: Delay on top of asyncResponseUplinkPeriods * uplink period duration to wait before timeout (seconds), range [0,3600]
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 3600
            default: 1200
      responses:
        '204':
          description: Delete requeste successfully processed
        '400':
          description: Invalid device id supplied
        '401':
          description: Unauthorized - invalid api key
        '403':
          description: Validation Error - device association check failure
        '404':
          description: Device not found
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /trackers/{deviceEUI}:
    get:
      tags:
        - Tracker
      summary: Get tracker information
      description: Get tracker type
      operationId: getTracker
      parameters:
        - name: deviceEUI
          in: path
          description: Device id to retrieve
          required: true
          schema:
            type: string
        - name: blePasskey
          in: query
          required: false
          description: true if BLE passkey is requested.
          schema:
            type: boolean
            default: false
        - name: hardwareIdHash
          in: query
          description: Hardware ID hash, base64 encoded. Required if blePasskey is true. If provided, the hardware ID hash will be checked before returning tracker information.
          required: false
          schema:
            type: string
            format: byte
            example: MDQ4MDQwNDMxOURGNDNEOTkwMEZFNDg3QjQwMEVGNjkyMkJGNDYyNzE1QTU0Q0Q3
      responses:
        '200':
          description: Tracker information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tracker'
        '400':
          description: Invalid device id supplied
        '401':
          description: Unauthorized - Invalid API key
        '403':
          description: Forbidden - Hardware ID hash verification failed
        '404':
          description: Device not found
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /account/password:
    put:
      summary: Change user's password
      description: Change password a client who is logged in.
      x-since-version: 1.3.0
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                current_password:
                  description: The current
                  type: string
                  format: password
                new_password:
                  description: The new password that the user wants to change to
                  type: string
                  format: password
              required:
                - current_password
                - new_password
      tags:
        - Account
      responses:
        '201':
          description: The password updated successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
        '403':
          description: Forbidden
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /account/image:
    put:
      summary: Change user account image
      description: Change the user account image
      x-since-version: 1.4.0
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                imageRef:
                  description: The uri to the image
                  type: string
                  format: uri
              required:
                - imageRef
      tags:
        - Account
      responses:
        '201':
          description: The image is changed successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /account/language:
    get:
      summary: Get user profile language setting
      description: Get user profile language setting
      x-since-version: 1.5.1
      parameters:
        - description: User realm Id, used in admin call
          in: query
          name: realmId
          required: false
          schema:
            type: string
        - description: User Id, used in admin call
          in: query
          name: userId
          required: false
          schema:
            type: string
      tags:
        - Account
      responses:
        '200':
          description: User locale retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locale'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
        '404':
          description: Not found - no language setting
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    put:
      summary: Set user profile language
      description: Set user profile language
      x-since-version: 1.5.0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Locale'
      tags:
        - Account
      responses:
        '201':
          description: The user profile locale is changed successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /account:
    delete:
      summary: Delete the user account
      description: Delete the user account
      x-since-version: 1.7.0
      tags:
        - Account
      responses:
        '204':
          description: The user account is deleted successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /account/logout:
    post:
      summary: Logout user
      description: Logout a user
      x-since-version: 1.8.0
      parameters:
        - description: Latest refresh token
          in: query
          name: refreshToken
          required: true
          schema:
            type: string
      tags:
        - Account
      responses:
        '201':
          description: Log out successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
        '403':
          description: Forbidden
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /share/{deviceEUI}:
    post:
      summary: Start sharing a tracker
      description: Start sharing a tracker
      x-since-version: 1.4.0
      parameters:
        - name: deviceEUI
          in: path
          description: Device id to share
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Recipient'
      tags:
        - Share
      responses:
        '201':
          description: The share with the provided sharingId is successfully created
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - invalid api key
        '403':
          description: Forbidden - The user is not owner of the device. Or the sharingId is registered in different realm
        '500':
          description: Internal Error
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /realms:
    get:
      tags:
        - Realm
      summary: Get the realm names having a parentSubscriber ID and a parentRealm ID matching the current user subscriber ID and DX profile ID.
      description: Get realm Ids
      operationId: getRealms
      x-since-version: 1.4.0
      responses:
        '200':
          description: Realm ids retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RealmId'
        '401':
          description: Unauthorized - invalid api key
        '404':
          description: end user not found
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /endUsers:
    get:
      tags:
        - End user
      summary: Get end users
      description: Get end users
      operationId: getEndUsers
      x-since-version: 1.4.0
      parameters:
        - description: User realm Id
          in: query
          name: realmId
          required: true
          schema:
            $ref: '#/components/schemas/RealmId'
        - description: Paging offset
          in: query
          name: first
          required: false
          schema:
            type: integer
            default: 0
        - description: Maximum number of endUsers in page
          in: query
          name: max
          required: false
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: End users retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EndUser'
        '401':
          description: Unauthorized - invalid api key
        '404':
          description: end user not found
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /endUsers/{userEmailAddress}:
    put:
      tags:
        - End user
      summary: Update end user
      description: Update end user
      operationId: UpdateEndUser
      x-since-version: 1.4.0
      parameters:
        - description: Email address of the end user to update.
          in: path
          name: userEmailAddress
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUser'
        description: Contents of the end user to update.
        required: true
      responses:
        '201':
          description: End user updated successfully.
        '400':
          description: Bad request
        '401':
          description: Unauthorized - invalid api key
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    delete:
      tags:
        - End user
      description: Deletes the end user corresponding to the provided user email address
      summary: Delete end user
      operationId: DeleteEndUser
      x-since-version: 1.4.0
      parameters:
        - description: Email address of the end user to delete.
          in: path
          name: userEmailAddress
          required: true
          schema:
            type: string
        - description: User realm Id
          in: query
          name: realmId
          required: true
          schema:
            $ref: '#/components/schemas/RealmId'
      responses:
        '204':
          description: End user deleted successfully.
          content: {}
        '400':
          description: Any error when processing the request
        '401':
          description: Unauthorized - invalid api key or user not authorized for access
        '404':
          description: Not Found
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /appVersion:
    post:
      tags:
        - App Version
      summary: Create app version
      description: create Mobile App Version
      operationId: createAppVersion
      x-since-version: 1.6.0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppVersion'
      responses:
        '201':
          description: App Version created successfully.
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    get:
      tags:
        - App Version
      summary: Get app version
      description: Get Mobile App Version
      operationId: getAppVersion
      x-since-version: 1.6.0
      responses:
        '200':
          description: App Version retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppVersion'
        '401':
          description: Unauthorized - invalid api key
        '404':
          description: App Version not found
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    put:
      tags:
        - App Version
      summary: Update app version
      description: update Mobile App Version
      operationId: updateAppVersion
      x-since-version: 1.6.0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppVersion'
      responses:
        '201':
          description: App Version updated successfully.
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    delete:
      tags:
        - App Version
      summary: delete app version
      description: delete Mobile App Version for subscriber
      operationId: deleteAppVersion
      x-since-version: 1.6.0
      responses:
        '204':
          description: App Version deleted successfully.
        '401':
          description: Unauthorized
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
servers:
  - url: '/location-integration-module/latest/api'
components:
  securitySchemes:
    bearerAuth:
      description: 'Enter your access token here without prefix "bearer " '
      type: http
      scheme: bearer
      bearerFormat: JWT
    keycloak:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: '/auth/realms//protocol/openid-connect/auth'
          scopes: {}
    Dx-Admin:
      type: oauth2
      description: |
        **This authorization is deprecated. Service account authentication should be used.**

        Enter your ThingPark credentials with dx-profile-id as prefix. 

        Example: dev1-api/test@abeeway.com
      flows:
        clientCredentials:
          tokenUrl: '/admin/latest/api/oauth/token'
          scopes: {}
  schemas:
    Locale:
      type: object
      description: Locale of the account
      properties:
        language:
          type: string
          example: en
    RealmId:
      type: string
      description: Realm ID
      example: le-lab
    Tracker:
      type: object
      properties:
        deviceEUI:
          type: string
          description: Device EUI
          example: 20635F00C5000293
        type:
          type: string
          description: Tracker type
        product:
          type: string
          description: Product Name of the Tracker
        productDescription:
          type: string
          description: Description of the Product
        maxFlashMemorySize:
          type: integer
          description: max flash memory size available for firmware (bytes)
        blePasskey:
          type: string
          description: blePasskey for the device
          example: 012345
      example:
        deviceEUI: 20635F00C5000293
        type: Smart Badge
        product: Smart Badge V1 EU 1.0
        productDescription: Smart Badge v1 EU full pcb 1.0
        maxFlashMemorySize: 238000
    Recipient:
      type: object
      properties:
        sharingId:
          type: string
      required:
        - sharingId
      example:
        sharingId: john.doe@abeeway.com
    DeviceRegistrationInfo:
      type: object
      properties:
        hardwareIDHash:
          type: string
          format: byte
          description: Hardware ID hash, base64 encoded
          example: MDQ4MDQwNDMxOURGNDNEOTkwMEZFNDg3QjQwMEVGNjkyMkJGNDYyNzE1QTU0Q0Q3
        deviceEUI:
          type: string
          format: byte
          description: Device EUI, base64 encoded
          example: MjA2MzVGMDBDNTAwMDI5Mw==
      required:
        - hardwareIDHash
        - deviceEUI
      example:
        hardwareIDHash: MDQ1NDA0MDU5Qjk5RjJCM0ZBQjFDQUFBOTlFOUU0QkVGNUJDRDVCNzg1RjFGQUJE
        deviceEUI: MjA2MzVGMDBDNjAwMDI2QQ==
    EndUser:
      type: object
      properties:
        firstName:
          type: string
          description: User first name
        lastName:
          type: string
          description: User last name
        userEmailAddress:
          type: string
          description: User email address
        firmwareUpgradeAdvanced:
          type: boolean
          description: It is true when the end user has the role to upgrade the firmware.
        realmId:
          $ref: '#/components/schemas/RealmId'
    AppVersion:
      type: object
      properties:
        androidAppMinimumVersion:
          type: string
          description: Required minimum version for Android app
          example: 1.0.0
        iosAppMinimumVersion:
          type: string
          description: Required minimum version for IOS app
          example: 1.0.0
        androidAppSuggestedVersion:
          type: string
          description: Suggested version for Android app
          example: 1.2.0
        iosAppSuggestedVersion:
          type: string
          description: Suggested version for IOS app
          example: 1.2.1
    Token:
      type: object
      properties:
        accessToken:
          type: string
          description: The access token
        expirationTime:
          type: string
          description: The expiration time of the token