{"openapi":"3.1.0","info":{"title":"Things MQTT Bindings API","description":"This specification describes the MQTT Bindings API of the KPN Things Platform.","contact":{"name":"KPN Things Support","url":"https://portal.kpnthings.com/support","email":"iot-developer@kpn.com"},"version":"0.2.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"paths":{"/mqtt/bindings":{"get":{"summary":"Retrieve MQTT bindings, filtered by query parameters.","description":"Retrieve all MQTT bindings that match the query parameters given.","operationId":"searchMqttBindings","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"clientId","in":"query","description":"Include only MQTT bindings for devices that are owned by the provided clientId.  If clientId is omitted, bindings from all devices owned by the calling client are included.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","example":null},"example":"79658ca8-f1ba-4c25-b824-93813e9fba76"},{"name":"deviceId","in":"query","description":"Include only MQTT bindings for the device identified by the provided deviceId.","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/DeviceId","example":null},"example":"89b053c5-7380-4fc3-8fe6-8792e746580f"},{"name":"username","in":"query","description":"Include only MQTT bindings where the username equals the provided username.","style":"form","explode":true,"schema":{"type":"string","example":null},"example":"urn:dev:DVNUUID:89b053c5-7380-4fc3-8fe6-8792e746580f:"},{"name":"createdBefore","in":"query","description":"Include only MQTT bindings created before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-05-01T00:00:00Z"},{"name":"createdSince","in":"query","description":"Include only MQTT bindings created at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-05-01T00:00:00Z"},{"name":"modifiedBefore","in":"query","description":"Include only MQTT bindings modified before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-04-01T00:00:00Z"},{"name":"modifiedSince","in":"query","description":"Include only MQTT bindings modified at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-04-01T00:00:00Z"}],"responses":{"200":{"description":"Page of filtered MQTT bindings. Only bindings that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfMqttBindings","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.read"]}]},"post":{"summary":"Create a new MQTT binding.","description":"Create a new MQTT binding.","operationId":"createMqttBinding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttBinding","example":null}}},"required":true},"responses":{"201":{"description":"The newly created MQTT binding'.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.create"]}]}},"/mqtt/bindings/{bindingId}":{"get":{"summary":"Retrieve a MQTT binding by ID.","operationId":"getMqttBinding","parameters":[{"name":"bindingId","in":"path","description":"MQTT binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"responses":{"200":{"description":"The MQTT binding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.read"]}]},"put":{"summary":"Update a MQTT binding.","operationId":"setMqttBinding","parameters":[{"name":"bindingId","in":"path","description":"MQTT binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttBinding"}}},"required":true},"responses":{"200":{"description":"The updated MQTT binding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.update"]}]},"delete":{"summary":"Delete a MQTT binding.","operationId":"deleteMqttBinding","parameters":[{"name":"bindingId","in":"path","description":"MQTT Binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"responses":{"204":{"description":"MQTT binding has been deleted successfully."}},"security":[{"BearerAuth":["connector-binding.delete"]}]}}},"components":{"schemas":{"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","example":"478a82d4-128f-47a6-aa61-2eac3f2a23ad","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","example":"imei:350266800610993","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","example":"deveui:ea8fa35e2cf3489f","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","example":"dvnuuid:ed8b73ac-f48f-4457-8ccc-9926cf28979f","pattern":"(?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$","title":"DvnUuidDeviceId"},"DeviceUrn-imei":{"type":"string","description":"IMEI-based device URN","example":"urn:dev:imei:350266800610993","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","example":"urn:dev:deveui:ea8fa35e2cf3489f","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","example":"urn:dev:dvnuuid:ed8b73ac-f48f-4457-8ccc-9926cf28979f","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid","example":null},{"$ref":"#/components/schemas/DeviceId-imei","example":null},{"$ref":"#/components/schemas/DeviceId-deveui","example":null},{"$ref":"#/components/schemas/DeviceId-dvnuuid","example":null},{"$ref":"#/components/schemas/DeviceUrn-imei","example":null},{"$ref":"#/components/schemas/DeviceUrn-deveui","example":null},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid","example":null}],"title":"DeviceId","example":null},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{},"example":null},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page.","example":null},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page.","example":null}},"required":["items"],"title":"Page","example":null},"MqttBinding":{"type":"object","description":"A binding of a device to the MQTT connector.","properties":{"id":{"type":"string","format":"uuid","description":"The id of the binding.","example":"224ecc46-291d-482b-993f-c8b508adb0da","readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The id of the device that is bound to the MQTT connector by the binding.","example":"11fb8757-c3a7-4a53-96e8-8d6b5a2f3b05"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the binding is created in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the binding.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the binding is last modified in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the binding.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"username":{"type":"string","description":"The username the device uses when authenticating with the MQTT connector. This value is set to the device URN by the system when the binding is created.","example":"urn:dev:IMEI:357292748642776:","readOnly":true},"password":{"type":"string","description":"The password the device uses when authenticating with the MQTT connector. Must be at least 24 characters, with at least one lower case letter, upper case letter, number and special character.","example":"G6sdt9{4R8QmORTPt%zW.*:yr@}vRLzc","minLength":24,"writeOnly":true}},"required":["deviceId"],"title":"MqttBinding","example":null},"PageOfMqttBindings":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page","example":null},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MqttBinding"},"example":null}},"example":null}],"description":"A paginated list of MQTT bindings","title":"PageOfMqttBindings","example":null},"Problem":{"type":"object","description":"Error information details","properties":{"type":{"type":"string","format":"uri-reference","default":"about:blank","description":"A URI reference that uniquely identifies the problem type only in the\ncontext of the provided API. Opposed to the specification in RFC-9457,\nit is neither recommended to be dereferenceable and point to a\nhuman-readable documentation nor globally unique for the problem type.","example":"/some/uri-reference"},"title":{"type":"string","description":"A short summary of the problem type. Written in English and readable\nfor engineers, usually not suited for non technical stakeholders and\nnot localized.","example":"some title for the error situation"},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","example":400,"exclusiveMaximum":600,"minimum":100},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem that is helpful to locate the problem and give advice on how\nto proceed. Written in English and readable for engineers, usually not\nsuited for non technical stakeholders and not localized.","example":"Some description for the error situation"},"instance":{"type":"string","format":"uri-reference","description":"A URI reference that identifies the specific occurrence of the problem,\ne.g. by adding a fragment identifier or sub-path to the problem type.\nMay be used to locate the root of this problem in the source code.","example":"/some/uri-reference#specific-occurrence-context"}},"title":"Problem","example":null}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":{"cursor":{"name":"cursor","in":"query","description":"String that encodes all necessary information to retrieve a page.","style":"form","explode":true,"schema":{"type":"string","format":"cursor"}},"limit":{"name":"limit","in":"query","description":"Limit the number of results (per page).","style":"form","explode":true,"schema":{"type":"integer","default":50}},"sort":{"name":"sort","in":"query","description":"Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.","style":"form","explode":true,"schema":{"type":"string"},"example":"createdAt,-name"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}