openapi: 3.0.0
info:
  description: API to configure secrets on ThingPark X Location Engine Platform.
  title: ThingPark X Location Engine Key Management API
  version: 3.0.0
externalDocs:
  description: For more information, please check the online examples in this documentation.
  url: '/location-key-management/latest/doc/index.html'
paths:
  /geolocationProviders:
    get:
      tags:
        - Geolocation
      summary: Retrieves the list of available geolocation providers
      description: Retrieves the list of available geolocation providers
      parameters:
        - name: subscriberId
          in: query
          description: The subscriberId for the specific Operator. Required incase of Operator scope for DX API Authentication.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: The list of geolocation providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeolocationProvider'
              examples:
                response:
                  value:
                    - id: google
                      name: Google
                      description: Google geolocation provider
                      configurationSchema:
                        type: object
                        required:
                          - apiKey
                        properties:
                          apiKey:
                            type: string
                            format: password
                            description: Google specific API Key
                          wifiGeolocation:
                            type: boolean
                            description: Enable Google Wifi geolocation
                          reverseGeocoding:
                            type: boolean
                            description: Enable Google reverse geocoding
                          elevation:
                            type: boolean
                            description: Enable Google elevation resolution
                      moduleId: google
                      producerId: abeeway
                      version: 1.0.0
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /geolocationProviders/{geolocationProviderId}:
    get:
      tags:
        - Geolocation
      summary: Retrieves a geolocation provider
      description: Retrieves a geolocation provider
      parameters:
        - name: geolocationProviderId
          in: path
          description: The geolocation provider ID
          required: true
          schema:
            type: string
        - name: subscriberId
          in: query
          description: The subscriberId for the specific Operator. Required incase of Operator scope for DX API Authentication.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: The geolocation provider representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationProvider'
              examples:
                response:
                  value:
                    id: google
                    name: Google
                    description: Google geolocation provider
                    configurationSchema:
                      type: object
                      required:
                        - apiKey
                      properties:
                        apiKey:
                          type: string
                          format: password
                          description: Google specific API Key
                        wifiGeolocation:
                          type: boolean
                          description: Enable Google Wifi geolocation
                        reverseGeocoding:
                          type: boolean
                          description: Enable Google reverse geocoding
                        elevation:
                          type: boolean
                          description: Enable Google elevation resolution
                    moduleId: google
                    producerId: abeeway
                    version: 1.0.0
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /binders:
    get:
      tags:
        - Binder
      summary: Retrieves the list of available binders
      description: Retrieves the list of available binders
      responses:
        '200':
          description: The list of binders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Binder'
              example:
                - id: objenious
                  name: objenious
                  description: Actility Objenious Operator
                  connection:
                    configurationSchema:
                      type: object
                      required:
                        - apiKey
                      properties:
                        apiKey:
                          type: string
                          format: password
                          description: Operator Specific API Key
                        subscriberToken:
                          type: string
                          format: string
                          readOnly: true
                          description: Signed JWT Token containing the Subscriber details specific to the Operator.
                    attributes: null
                  moduleId: objenious
                  producerId: actility
                  version: 1.2.0
                - id: liveobjects
                  name: live objects
                  description: Actility Orange Operator
                  connection:
                    configurationSchema:
                      type: object
                      required:
                        - apiKey
                      properties:
                        apiKey:
                          type: string
                          format: password
                          description: Operator Specific API Key
                        subscriberToken:
                          type: string
                          format: string
                          readOnly: true
                          description: Signed JWT Token containing the Subscriber details specific to the Operator.
                    attributes: null
                  moduleId: liveobjects
                  producerId: actility
                  version: 1.2.0
                - id: tpw
                  name: tpw
                  description: Actility TPW Operator
                  connection:
                    configurationSchema:
                      type: object
                      nullable: 'true'
                      properties:
                        tpwKeys:
                          type: object
                          description: 'Operator Specific API Key '
                          properties:
                            asid:
                              type: string
                              description: Operator specific Application Server Id
                            tiak:
                              type: string
                              format: password
                              description: Operator Specific Tunnel Interface Authentication Key
                        tpwASConfiguration:
                          type: array
                          description: The list of application server configurations for TPW Operator
                          items:
                            type: object
                            properties:
                              encryptedASTK:
                                type: string
                                format: password
                                description: Operator Specific encrypted ASTK
                              kekLabel:
                                type: string
                                description: Operator specific Kek Label
                        subscriberToken:
                          type: string
                          format: string
                          readOnly: true
                          description: Signed JWT Token containing the Subscriber details specific to the Operator.
                    attributes:
                      rsaPublicKey: MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAjer6SZ057h9jQVrWtw350ARDq0PzQNWh6TesS0PWon7PYXe2PWM18R4LU9hThgYfMuJEaYm+xbtYgVLfCdVVKL1Z2a1GqpyHvghocAAFsPVgQaXJEWJWWtsWBTIU6qjVvQ+GCMWl07YuHKu1I9m9TQY9Vr6+HNUImGkAQb1OFJcMfoTDH64cA91+5E53Vv13/ZaqDQACpdICkC7gRPElF8tRSiT4PdgwMhGdPQD8S0Xud57c/z1V+zpUjRa5HIPsjAJ+qQRkbP1hMdVMaAMh/QGbwzv5VNqtfQGm0GAivBbQoHZBwH8RwguWNSZFYFxgw2mHHW/Zqd6CK2dD/NBJI4SIWqMvV35BFUUHuOHE5pU0tNrLiS2LNS5zu3Hqti0STyWC84pgIXtFrZz3n/V1NJcYu9ftB2ceyTedV87e1iZNHw0R+mpLWCI/83Ggo4XO4i9ZPVWxnEf12OSNACmbQytB4DNmTWhsmf62kX2g2Pm7m+0zWavUl3zNe3iB7OGPprnvJ9SHVI1iLHoRtq6d8K4K9IAtUgNyeo4hSM9xaxS7MGxXW8qlVYQGAJNmHkLk4gSK/Gt6hN1wdhrC0aBUktweEIgyqwX3TmKXgmsElbCD0N44G0wUMbs2xZhHJahgR24g4PRkzFvfRNIksh+HQWknagMss8sbU8Bu2fUJcvECAwEAAQ==
                  moduleId: tpw
                  producerId: actility
                  version: 1.2.0
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /binders/{binderId}:
    get:
      tags:
        - Binder
      summary: Retrieves a binder
      description: Retrieves a binder by id
      parameters:
        - name: binderId
          in: path
          description: The binder ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The binder representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Binder'
              example:
                id: tpw
                name: tpw
                description: Actility TPW Operator
                connection:
                  configurationSchema:
                    type: object
                    nullable: 'true'
                    properties:
                      tpwKeys:
                        type: object
                        description: 'Operator Specific API Key '
                        properties:
                          asid:
                            type: string
                            description: Operator specific Application Server Id
                          tiak:
                            type: string
                            format: password
                            description: Operator Specific Tunnel Interface Authentication Key
                      tpwASConfiguration:
                        type: array
                        description: The list of application server configurations for TPW Operator
                        items:
                          type: object
                          properties:
                            encryptedASTK:
                              type: string
                              format: password
                              description: Operator Specific encrypted ASTK
                            kekLabel:
                              type: string
                              description: Operator specific Kek Label
                      subscriberToken:
                        type: string
                        format: string
                        readOnly: true
                        description: Signed JWT Token containing the Subscriber details specific to the Operator.
                  attributes:
                    rsaPublicKey: MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAjer6SZ057h9jQVrWtw350ARDq0PzQNWh6TesS0PWon7PYXe2PWM18R4LU9hThgYfMuJEaYm+xbtYgVLfCdVVKL1Z2a1GqpyHvghocAAFsPVgQaXJEWJWWtsWBTIU6qjVvQ+GCMWl07YuHKu1I9m9TQY9Vr6+HNUImGkAQb1OFJcMfoTDH64cA91+5E53Vv13/ZaqDQACpdICkC7gRPElF8tRSiT4PdgwMhGdPQD8S0Xud57c/z1V+zpUjRa5HIPsjAJ+qQRkbP1hMdVMaAMh/QGbwzv5VNqtfQGm0GAivBbQoHZBwH8RwguWNSZFYFxgw2mHHW/Zqd6CK2dD/NBJI4SIWqMvV35BFUUHuOHE5pU0tNrLiS2LNS5zu3Hqti0STyWC84pgIXtFrZz3n/V1NJcYu9ftB2ceyTedV87e1iZNHw0R+mpLWCI/83Ggo4XO4i9ZPVWxnEf12OSNACmbQytB4DNmTWhsmf62kX2g2Pm7m+0zWavUl3zNe3iB7OGPprnvJ9SHVI1iLHoRtq6d8K4K9IAtUgNyeo4hSM9xaxS7MGxXW8qlVYQGAJNmHkLk4gSK/Gt6hN1wdhrC0aBUktweEIgyqwX3TmKXgmsElbCD0N44G0wUMbs2xZhHJahgR24g4PRkzFvfRNIksh+HQWknagMss8sbU8Bu2fUJcvECAwEAAQ==
                moduleId: tpw
                producerId: actility
                version: 1.2.0
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /connections:
    get:
      tags:
        - Connection
      summary: Retrieves the list of connections to a binder
      description: Retrieves the list of connections to a binder
      operationId: listConnections
      responses:
        '200':
          description: The list of connections to a binder
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connection'
              example:
                - configuration:
                    apiKey: '*****'
                    subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                  binderId: liveobjects
                  id: '1'
                  name: Orange API Key
                - configuration:
                    apiKey: '*****'
                    subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                  binderId: objenious
                  id: '2'
                  name: Objenious API Key
                - configuration:
                    tpwKeys:
                      asid: as1234
                      tiak: '*****'
                    tpwASConfiguration:
                      - encryptedAstk: '*****'
                        kekLabel: ''
                      - encryptedAstk: '*****'
                        kekLabel: kek123
                    subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                  binderId: tpw
                  id: '3'
                  name: TPW Operator Keys
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    post:
      tags:
        - Connection
      summary: Creates a connection to a binder
      description: Creates a connection to a binder
      operationId: createConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Connection'
        description: The connection to a binder to be created
        required: true
      responses:
        '201':
          description: The connection to a binder is created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
              example:
                configuration:
                  apiKey: '*****'
                  subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                binderId: liveobjects
                id: '1'
                name: Orange API Key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /connections/{connectionId}:
    get:
      tags:
        - Connection
      summary: Retrieves the connection to a binder
      description: Retrieves the connection to a binder
      operationId: getConnection
      parameters:
        - name: connectionId
          in: path
          description: The connection ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The connection representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
              example:
                configuration:
                  apiKey: '*****'
                  subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                binderId: objenious
                id: '2'
                name: Objenious API Key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    patch:
      tags:
        - Connection
      summary: Patches the connection to a binder
      description: Patches the connection to a binder
      operationId: patchConnection
      parameters:
        - name: connectionId
          in: path
          description: The connection ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionUpdate'
        description: The connection to a binder to be updated
        required: true
      responses:
        '200':
          description: The connection to a binder is updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
              example:
                configuration:
                  apiKey: '*****'
                  subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                binderId: liveobjects
                id: '1'
                name: Orange API Key Update
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    put:
      tags:
        - Connection
      summary: Updates the connection to a binder
      description: Updates the connection to a binder
      operationId: updateConnection
      parameters:
        - name: connectionId
          in: path
          description: The connection ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Connection'
        description: The connection to a binder to be updated
        required: true
      responses:
        '200':
          description: The connection to a binder is updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
              example:
                configuration:
                  apiKey: '*****'
                  subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                binderId: liveobjects
                id: '1'
                name: Orange API Key Update
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    delete:
      tags:
        - Connection
      summary: Delete the connection to a binder
      description: Delete the connection to a binder
      operationId: deleteConnection
      parameters:
        - name: connectionId
          in: path
          description: The connection ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The connection to a binder is deleted
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /geolocationConnections:
    get:
      tags:
        - GeolocationConnection
      summary: Retrieves the list of connections to a geolocation provider
      description: Retrieves the list of connections to a geolocation provider
      operationId: listGeolocationConnections
      responses:
        '200':
          description: The list of geolocation connections to a geolocation provider
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeolocationConnection'
              example:
                - configuration:
                    apiKey: '*****'
                    wifiGeolocation: true
                    reverseGeocoding: true
                    elevation: true
                  providerId: google
                  id: '1'
                  name: Google API Key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    post:
      tags:
        - GeolocationConnection
      summary: Creates a connection to a geolocation provider
      description: Creates a connection to a geolocation provider
      operationId: createGeolocationConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeolocationConnection'
        description: The connection to a geolocation provider to be created
        required: true
      responses:
        '201':
          description: The connection to a geolocation provider is created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationConnection'
              example:
                - configuration:
                    apiKey: '*****'
                    wifiGeolocation: true
                    reverseGeocoding: true
                    elevation: true
                  providerId: google
                  id: '1'
                  name: Google API Key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /geolocationConnections/{geolocationConnectionId}:
    get:
      tags:
        - GeolocationConnection
      summary: Retrieves the connection to a geolocation provider
      description: Retrieves the connection to a geolocation provider
      operationId: getGeolocationConnection
      parameters:
        - name: geolocationConnectionId
          in: path
          description: The geolocation connection ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The geolocation connection representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
              example:
                configuration:
                  apiKey: '*****'
                  wifiGeolocation: true
                  reverseGeocoding: true
                  elevation: true
                providerId: google
                id: '1'
                name: Google API Key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    patch:
      tags:
        - GeolocationConnection
      summary: Patches the connection to a geolocation provider
      description: Patches the connection to a geolocation provider
      operationId: patchGeolocationConnection
      parameters:
        - name: geolocationConnectionId
          in: path
          description: The geolocation connection ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeolocationConnectionUpdate'
        description: The connection to a geolocation provider to be updated
        required: true
      responses:
        '200':
          description: The connection to a geolocation provider is updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationConnection'
              example:
                configuration:
                  apiKey: '*****'
                  wifiGeolocation: true
                  reverseGeocoding: true
                  elevation: true
                providerId: google
                id: '1'
                name: Google API Key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    put:
      tags:
        - GeolocationConnection
      summary: Updates the connection to a geolocation provider
      description: Updates the connection to a geolocation provider
      operationId: updateGeolocationConnection
      parameters:
        - name: geolocationConnectionId
          in: path
          description: The geolocation connection ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeolocationConnection'
        description: The connection to a binder to be updated
        required: true
      responses:
        '200':
          description: The connection to a geolocation provider is updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationConnection'
              example:
                configuration:
                  apiKey: '*****'
                  wifiGeolocation: true
                  reverseGeocoding: true
                  elevation: true
                providerId: google
                id: '1'
                name: Google API Key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    delete:
      tags:
        - GeolocationConnection
      summary: Deletes the connection to a geolocation provider
      description: Deletes the connection to a geolocation provider
      operationId: deleteGeolocationConnection
      parameters:
        - name: geolocationConnectionId
          in: path
          description: The geolocation connection ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The connection to a geolocation provider is deleted
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /events:
    get:
      tags:
        - Events
      summary: Retrieves events on the binders 
      description: Retrieves events on the binders on the Thingpark X Location Key Management Platform
      operationId: listEvents
      parameters:
        - name: startTime
          in: query
          description: The (inclusive) start time from which the events will be filtered. Example- 2019-05-21T15:00:55.888+02:00
          required: false
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          description: The (inclusive) end time until which the events will be filtered. Example- 2019-05-21T15:40:55.888+02:00
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: The list of events for the binders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/events'
              example:
                - eventTime: 1558600927.534
                  level: info
                  code: binder_connection-1
                  data:
                    id: 1
                    binderId: liveobjects
                    name: Orange API Key
                    configuration:
                      apiKey: '*****'
                      subscriberToken: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTk1NzA3MjksInN1YiI6IjEwMDAwNDQ4NSJ9.aR0CXyeZpaFowf7SFi02ftjOw0w0T1B3U1Uv_ohnuHM
                  message: API - CONNECTION CREATED
                - eventTime: 1558600952.415
                  level: info
                  code: binder_connection-2
                  data:
                    - op: remove
                      path: /id
                    - op: replace
                      path: /name
                      value: Orange API Key Update
                    - op: replace
                      path: /configuration/apiKey
                      value: JhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJnX2xGakxDQk9DV0x1d
                  message: API - CONNECTION UPDATED
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /apiKeys:
    get:
      tags:
        - ApiKey
      summary: Retrieves the list of Api keys
      description: Retrieves the list of Api keys
      operationId: listApiKeys
      responses:
        '200':
          description: The list of Api Keys for the subscriber or the user
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
              example:
                - apiKey: '*****'
                  scope: ALL
                  id: '1'
                  name: Example API key
                - apiKey: '*****'
                  scope: AS
                  id: '3'
                  name: another Example API key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
        '404':
          description: No Api Key found
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    post:
      tags:
        - ApiKey
      summary: Creates an Api key
      description: Creates an Api key
      operationId: createApiKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKey'
            example:
                scope: ALL
                name: Example API key
        description: Provide the scope and a name (optional) to the service to get an Api Key created
        required: true
      responses:
        '201':
          description: The created Api Key with the required scope and name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
              example:
                apiKey: 'ZGV2MS1hcGkvMTAwMDAxMTgwL2xlLWxhYi8yMWE5NWFkNC0yNjQzLTRiZDktYTY2ZS1mNDNhNTAxZjU5NmU=.MTIzZTQ1NjctZTg5Yi00MmQzLWE0NTYtNTU2NjQyNDQwMDAw'
                scope: ALL
                id: '1'
                name: Example API key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
  /apiKeys/{apiKeyId}:
    get:
      tags:
        - ApiKey
      summary: Retrieves an API key by id
      description: Retrieves an API key by id
      operationId: getApiKey
      parameters:
        - name: apiKeyId
          in: path
          description: The API key ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The Api Keys for the subscriber or the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
              example:
                apiKey: '*****'
                scope: ALL
                id: '1'
                name: Example API key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
        '404':
          description: No Api Key found by the id
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    put:
      tags:
        - ApiKey
      summary: Reset the API key
      description: Reset the API key if the user forgets it
      operationId: resetApiKey
      parameters:
        - name: apiKeyId
          in: path
          description: The API key ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The Api Key is reset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
              example:
                apiKey: 'ZGV2MS1hcGkvMTAwMDAxMTgwL2xlLWxhYi8yMWE5NWFkNC0yNjQzLTRiZDktYTY2ZS1mNDNhNTAxZjU5NmU=.MTIzZjQ1NjctZTg5Yi00MmQzLWE0NTYtNTU2NjQyNDQwMDAw'
                scope: ALL
                id: '1'
                name: Example API key
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
        '404':
          description: No Api Key found by the id
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
    delete:
      tags:
        - ApiKey
      summary: Revoke the API key
      description: Revoke the API key
      operationId: revokeApiKey
      parameters:
        - name: apiKeyId
          in: path
          description: The API key ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The API key is successfully revoked
        '400':
          description: Any error when processing the request
        '401':
          description: User not authorized to access
        '404':
          description: No Api Key found by the id
      security:
        - bearerAuth: []
          Dx-Admin: []
          keycloak: []
tags:
  - description: Binder configuration for operators on Thingpark X Location Engine.
    name: Binder
  - description: An active connection to a Binder configuration on Thingpark X Location Engine.
    name: Connection
  - description: Geolocation provider configuration for external geolocation  providers on Thingpark X Location Engine.
    name: Geolocation
  - description: An active connection to a geolocation provider configuration on Thingpark X Location Engine.
    name: GeolocationConnection
  - name: Events
    description: Events that occurred on the ThingPark X Location Engine Key Management platform for debugging purpose
  - name: ApiKey
    description: Api keys for TPX-LE
servers:
  - url: '/location-key-management/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:
    GeolocationProvider:
      description: Resource representing a geolocation provider on ThingPark X Location Engine.
      type: object
      properties:
        id:
          description: The geolocation provider identifier.
          type: string
          readOnly: true
        description:
          description: A complete description for this geolocation provider.
          type: string
          readOnly: true
        name:
          description: Name of the geolocation provider.
          type: string
          readOnly: true
        connection:
          $ref: '#/components/schemas/GeolocationProviderConnection'
        moduleId:
          type: string
          description: The geolocation provider module identifier. It is a module name uniquely identifying the geolocation provider within the given producerId
          readOnly: true
        producerId:
          type: string
          description: The geolocation provider producer identifier. It describes the entity providing the geolocation provider
          readOnly: true
        version:
          description: The geolocation provider version. It must follow the [Semantic Versioning](https://semver.org/) convention
          type: string
          readOnly: true
    GeolocationProviderConnection:
      type: object
      description: The JSON schema describing the configuration of the geolocation provider
      readOnly: true
      properties:
        configurationSchema:
          description: Resource representing a geolocation provider connection for a geolocation provider on ThingPark X Location Engine.
    Binder:
      description: Resource representing a Binder for an Operator on the ThingPark X Location Engine.
      type: object
      properties:
        id:
          description: The binder identifier.
          type: string
          readOnly: true
        description:
          description: A complete description for this Binder.
          type: string
          readOnly: true
        name:
          description: Name of the Binder provided.
          type: string
          readOnly: true
        connection:
          $ref: '#/components/schemas/BinderConnection'
        moduleId:
          type: string
          description: The binder module identifier. It is a module name uniquely identifying the binder within the given producerId
          readOnly: true
        producerId:
          type: string
          description: The binder producer identifier. It describes the entity providing the binder
          readOnly: true
        version:
          description: 'The binder version. It must follow the [Semantic Versioning](https://semver.org/) convention '
          type: string
          readOnly: true
    BinderConnection:
      description: Resource representing a binder connection for an Operator on the ThingPark X Location Engine.
      type: object
      readOnly: true
      properties:
        configurationSchema:
          type: object
          description: 'The JSON schema describing the configuration of the binder connection '
        attributes:
          type: object
          description: 'The JSON schema describing the attributes specific to this binder connection '
      title: BinderConnection
    Connection:
      type: object
      required:
        - configuration
        - binderId
      properties:
        configuration:
          type: object
          description: 'The connection configuration following the configurationSchema as described in the binder resource '
        binderId:
          type: string
          description: The binder identifier which creates this connection
        id:
          type: string
          description: The connection identifier
          readOnly: true
        name:
          type: string
          description: A user defined name describing this connection
      title: Connection
    ConnectionUpdate:
      type: object
      properties:
        configuration:
          type: object
          description: The connection configuration updating the binder connection
    GeolocationConnection:
      type: object
      required:
        - configuration
        - providerId
      properties:
        configuration:
          type: object
          description: The geolocation provider configuration following the configurationSchema as described in the geolocation provider resource
        providerId:
          type: string
          description: The geolocation provider identifier which creates this connection
        id:
          type: string
          description: The geolocation provider connection identifier
          readOnly: true
        name:
          type: string
          description: A user defined name describing this geolocation provider connection
      title: Connection
    GeolocationConnectionUpdate:
      type: object
      properties:
        configuration:
          type: object
          description: The geolocation provider configuration updating this binder connection
    events:
      type: array
      description: List of events on the ThingPark X Location Engine Key Management Platform
      items:
        $ref: '#/components/schemas/event'
    event:
      type: object
      required:
        - eventTime
        - level
        - code
        - message
      properties:
        eventTime:
          type: string
          format: date-time
          description: The date at which this event occurred
        level:
          type: string
          enum:
            - debug
            - info
            - warn
            - error
          description: The event level
        code:
          type: string
          description: |
            A code identifying the type of event that occurred on the IoT Flow platform. The code has the following pattern '{module}-{number}' where '{module}' is an identifier of an internal IoT Flow component and '{number}' is a unique number on that module identifying the current event
        data:
          type: object
          description: |
            Any data attached to this event. Each object is identified by its key in the data JSON object
        message:
          type: string
          description: |
            A human readable message describing this event
    ApiKey:
      type: object
      required:
        - scope
        - name
      properties:
        id: 
          type: string
          description: unique id of the API key
        apiKey:
          type: string
          description: the value of API key
        scope:
          type: string
          enum:
            - ALL
            - NS
            - AS
          description: the scope of the API key
        name:
          type: string
          description: the name of the API key
        