{ "openapi": "3.0.0", "info": { "title": "Logistics CHF API", "description": "Manages relationships between devices, institutions and patients", "version": "4.0.0", "contact": { "name": "API Support", "url": "http://cradle.analoggarage.com", "email": "cradle_maintainers@analog.com" } }, "externalDocs": { "description": "View All Docs", "url": "https://dhc-public.s3.amazonaws.com/index.html" }, "servers": [ { "url": "https://dhc.analoggarage.com/logistics", "description": "Development Server" }, { "url": "https://api.log.qa.care.analog.com/", "description": "QA Server" }, { "url": "https://api.log.pref.care.analog.com/", "description": "Perf Server" }, { "url": "https://api.log.hclqa.care.analog.com/", "description": "HCL QA Server" }, { "url": "https://api.log.care.analog.com/", "description": "Production Server" }, { "url": "http://127.0.0.1:8100/external", "description": "Local Development Server" } ], "paths": { "/sims/{simId}": { "get": { "operationId": "getSim", "summary": "get SIM card", "description": "Returns the specified SIM component", "parameters": [ { "$ref": "#/components/parameters/SimId" } ], "tags": [ "All", "API Key" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/GetSimResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/sims": { "get": { "operationId": "listSims", "summary": "List SIM cards", "description": "Retrieve and optionally filter SIMs", "parameters": [ { "$ref": "#/components/parameters/PageNumberQueryParam" }, { "$ref": "#/components/parameters/ItemsPerPageQueryParam" }, { "$ref": "#/components/parameters/SearchQueryParam" } ], "tags": [ "All", "API Key" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/ListSimsResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } }, "post": { "operationId": "registerSim", "summary": "Registers SIM card", "description": "Registers an individual SIM card.\n\n_SIM provisioning flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "All", "API Key" ], "requestBody": { "$ref": "#/components/requestBodies/RegisterSimRequest" }, "responses": { "200": { "$ref": "#/components/responses/RegisterSimResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "default": { "$ref": "#/components/responses/GenericError" } } } }, "/base-stations": { "get": { "operationId": "listBaseStations", "summary": "List base stations", "description": "Retrieve and filter base stations", "parameters": [ { "$ref": "#/components/parameters/PageNumberQueryParam" }, { "$ref": "#/components/parameters/ItemsPerPageQueryParam" }, { "$ref": "#/components/parameters/SearchQueryParam" } ], "tags": [ "All", "API Key" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/BaseStationListResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } }, "post": { "operationId": "registerBaseStation", "summary": "Registers base stations", "description": "Registers an individual base station.\n\n_Base station provision flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "All", "API Key" ], "requestBody": { "$ref": "#/components/requestBodies/RegisterBaseStationRequest" }, "responses": { "200": { "$ref": "#/components/responses/RegisterBaseStationResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "default": { "$ref": "#/components/responses/GenericError" } } } }, "/base-stations/{baseStationId}": { "put": { "operationId": "updateBaseStation", "summary": "Updates properties of the specified base-station", "description": "Updates the certificate or firmware version for the base-station specified by ID.\n\n_Base station provision flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "All", "API Key" ], "parameters": [ { "$ref": "#/components/parameters/BaseStationId" } ], "requestBody": { "$ref": "#/components/requestBodies/BaseStationUpdateRequest" }, "responses": { "200": { "$ref": "#/components/responses/BaseStationUpdateResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "default": { "$ref": "#/components/responses/GenericError" } } }, "get": { "operationId": "getBaseStationDetails", "summary": "Get the base station details", "description": "Fetches the base station details for the specified baseStationId.\n\n_Base station provision flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "All", "API Key" ], "parameters": [ { "$ref": "#/components/parameters/BaseStationId" } ], "responses": { "200": { "$ref": "#/components/responses/BaseStationDetailsResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "default": { "$ref": "#/components/responses/GenericError" } } } }, "/base-stations/{baseStationId}/links": { "get": { "operationId": "getBaseStationLinks", "summary": "Retrieves Base station links", "description": "Retrieves base station links for a given base station identifier\n\n_Base station provision flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "All", "API Key" ], "parameters": [ { "$ref": "#/components/parameters/BaseStationId" } ], "responses": { "200": { "$ref": "#/components/responses/BaseStationLinksResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "default": { "$ref": "#/components/responses/GenericError" } } } }, "/base-stations/certificates": { "post": { "operationId": "signBaseStationCertificate", "tags": [ "Certificates", "All", "API Key" ], "summary": "Issues MQTT certificates.", "description": "Issues a certificate signed by ADI intermediate CA.\n\n_Base station provision flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CertificateExchangeRequest" }, "responses": { "200": { "$ref": "#/components/responses/CertificateExchangeResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/device-kits": { "get": { "operationId": "listKits", "summary": "List kits", "description": "Retrieve and filter any partial or full kit-associations", "parameters": [ { "$ref": "#/components/parameters/PageNumberQueryParam" }, { "$ref": "#/components/parameters/ItemsPerPageQueryParam" }, { "$ref": "#/components/parameters/SearchQueryParam" } ], "tags": [ "All", "API Key" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/ListKitsResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } }, "post": { "operationId": "prepareKit", "summary": "Registers a new kit with wearable, base-station, and SIM association", "description": "Creates a new \"kit\" record to map base-stations, wearables, and SIMs together\n\n_kitting flow_\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "All", "API Key" ], "requestBody": { "$ref": "#/components/requestBodies/PrepareKitRequest" }, "responses": { "200": { "$ref": "#/components/responses/PrepareKitResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "default": { "$ref": "#/components/responses/GenericError" } } } }, "/device-kits/{deviceId}": { "delete": { "operationId": "unkitComponentsAndDeactivateKit", "summary": "Unkits all components from a kit, and deactivates device and all kit components if kit was active", "description": "Deactivates device-kit and notifies CPM. Device ID specified\nmay already belong to an active device-kit. If components belonging to the\nkit had not yet been activated, components are simply un-kitted for re-use.\n\n_Device deactivation flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "responses": { "200": { "$ref": "#/components/responses/DeactivateKitResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/device-kits/{deviceId}/customer-links": { "put": { "operationId": "allocateKit", "summary": "Allocate device-kit to a customer", "description": "Creates an association between the given device-kit\nand organization (healthcare institution). Should be performed\nafter kit has been prepared with all 3 components (wearable/basestation/sim)\n\n_Device allocation flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "requestBody": { "$ref": "#/components/requestBodies/AllocateKitRequest" }, "responses": { "200": { "$ref": "#/components/responses/AllocateKitResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/device-kits/{deviceId}/sim-links": { "put": { "operationId": "updateSimLinkOnKit", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "summary": "Updates SIM assocaitation for the device-kit specified by device ID", "description": "Updates the kit specified by device ID by associating it with the specified SIM.\nIf the device-kit is already associated with another SIM, the old SIM will be unlinked.\n\n_Device re-kitting flow_.\n", "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "requestBody": { "$ref": "#/components/requestBodies/UpdateKitSimRequest" }, "responses": { "200": { "$ref": "#/components/responses/UpdateKitSimResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } }, "patch": { "operationId": "swapSimOnActiveKit", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "summary": "Replaces SIM association for the allocated/active device-kit specified by device ID", "description": "Updates the already-active kit specified by device ID by associating it with a new SIM.\nSince the device-kit is already associated with an active SIM, the old SIM will be unlinked.\n\n_Device re-kitting flow_.\n", "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "requestBody": { "$ref": "#/components/requestBodies/SwapSimOnActiveKitRequest" }, "responses": { "200": { "$ref": "#/components/responses/UpdateKitSimResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/device-kits/{deviceId}/sim-links/{simId}": { "delete": { "operationId": "unlinkSimFromKit", "summary": "Unlink specified SIM from pre-existing kit", "description": "Removes assignment of the specified SIM from the device-kit.\nRequires that device-kit is not already activated or allocated.\n\n_Device re-kitting flow_.\n", "tags": [ "API Key", "All" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/SimId" } ], "responses": { "200": { "$ref": "#/components/responses/UnlinkSimResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/device-kits/{deviceId}/base-station-links": { "put": { "operationId": "updateKitBaseStation", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "summary": "Updates base station information", "description": "Associates device with base station.\n\n_Device re-kitting flow_.\n", "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "requestBody": { "$ref": "#/components/requestBodies/UpdateKitBaseStationRequest" }, "responses": { "200": { "$ref": "#/components/responses/UpdateKitBaseStationResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } }, "patch": { "operationId": "swapBaseStationOnActiveKit", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "summary": "Replaces base-station link on the allocated/active device-kit specified by device ID", "description": "Updates the already-active kit specified by device ID by associating it with a new base-station.\nSince the device-kit is already associated with an active B.S., the old one will be unlinked.\n\n_Device re-kitting flow_.\n", "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "requestBody": { "$ref": "#/components/requestBodies/SwapBaseStationOnActiveKitRequest" }, "responses": { "200": { "$ref": "#/components/responses/UpdateKitBaseStationResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/device-kits/{deviceId}/base-station-links/{baseStationId}": { "delete": { "summary": "Unlink device from base station", "description": "Removes assignment of base-station from the device-kit.\nRequires that device-kit is not already activated or allocated.\n\n_Device re-kitting flow_.\n", "operationId": "unlinkBaseStation", "tags": [ "API Key", "All" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/BaseStationId" } ], "responses": { "200": { "$ref": "#/components/responses/UnlinkBaseStationResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/devices": { "get": { "operationId": "listDevices", "summary": "List devices", "description": "Retrieve and filter wearable devices and their associations", "parameters": [ { "$ref": "#/components/parameters/PageNumberQueryParam" }, { "$ref": "#/components/parameters/ItemsPerPageQueryParam" }, { "$ref": "#/components/parameters/SearchQueryParam" } ], "tags": [ "All", "API Key" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/DeviceListResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } }, "post": { "operationId": "registerDevice", "summary": "Registers monitors", "description": "Registers an individual wearable device after manufacture.\n\n_Device provision flow_.\n", "tags": [ "All", "API Key" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/DeviceRegisterRequest" }, "responses": { "200": { "$ref": "#/components/responses/DeviceRegisterResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/devices/{deviceId}": { "put": { "operationId": "updateWearableDevice", "summary": "Updates specified properties of the wearable device", "description": "Updates the specified properties of the wearable device (currently only FW version)\n\n_Device provision flow_.\n", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "requestBody": { "$ref": "#/components/requestBodies/UpdateDeviceRequest" }, "responses": { "200": { "$ref": "#/components/responses/UpdateDeviceResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/patients/{patientId}/devices": { "put": { "operationId": "assignDeviceToPatient", "security": [ { "BearerAuth": [] } ], "summary": "Links device to a patient", "description": "Associate device and patient, notifies CPM.\n\n**Permissions**: `dv.activate:in.{institutionId}/x`.\n\n_Device allocation flow_.\n", "tags": [ "JWT", "All" ], "parameters": [ { "$ref": "#/components/parameters/PatientId" } ], "requestBody": { "$ref": "#/components/requestBodies/PatientDevicesUpdateRequest" }, "responses": { "200": { "$ref": "#/components/responses/AllocateDeviceResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/patients/{patientId}/devices/active": { "get": { "operationId": "getPatientDevice", "security": [ { "BearerAuth": [] } ], "summary": "Get device linked to a patient", "description": "Associate device and patient, notifies CPM.\n\n**Permissions**: `dv.configure:in.{institutionId}/r`.\n", "tags": [ "JWT", "All" ], "parameters": [ { "$ref": "#/components/parameters/PatientId" } ], "responses": { "200": { "$ref": "#/components/responses/PatientAllocatedDeviceResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/devices/{deviceId}/patients/{patientId}": { "delete": { "summary": "Recall device from a patient", "description": "Deassociate device from the patient, notify CPM about the change.\n", "operationId": "unlinkDeviceFromPatient", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "API Key", "All" ], "parameters": [ { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/PatientId" } ], "responses": { "200": { "$ref": "#/components/responses/StatusResult" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/certificates/cloud": { "post": { "operationId": "exchangeCertificates", "tags": [ "Certificates", "All", "JWT" ], "summary": "Issues MQTT certificates.", "description": "Issues a certificate signed by ADI intermediate CA.\n\n**Permissions**: `dv.configure:in.{institutionId}/rw`.\n", "security": [ { "BearerAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CertificateExchangeRequest" }, "responses": { "200": { "$ref": "#/components/responses/CertificateExchangeResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/certificates/peers/base-stations": { "post": { "operationId": "signBaseStationPeerCertificate", "tags": [ "Certificates", "All", "API Key" ], "summary": "Signs and returns a new ECC peer-certificate", "description": "Issues a peer-certificate signed by ADI intermediate CA.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/PeerCertificateRequest" }, "responses": { "200": { "$ref": "#/components/responses/PeerCertificateResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/certificates/peers/apps": { "post": { "operationId": "signAppPeerCertificate", "tags": [ "Certificates", "All", "JWT" ], "summary": "Signs and returns a new ECC peer-certificate for mobile app", "description": "Issues a peer-certificate signed by ADI intermediate CA.\n\n**Permissions**: `dv.configure:in.{institutionId}/rw`.\n", "security": [ { "BearerAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/PeerCertificateRequest" }, "responses": { "200": { "$ref": "#/components/responses/PeerCertificateResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } }, "/device-keys/{deviceId}/": { "get": { "operationId": "getDeviceKey", "security": [ { "BearerAuth": [] } ], "summary": "Get device key ID", "description": "Returns the secret symmetric key used by the wearable specified by ID.\n\n**Permissions**: `dv.cpm.master:dv.{deviceId}/r`.\n", "tags": [ "JWT", "All" ], "parameters": [ { "$ref": "#/components/parameters/DeviceId" } ], "responses": { "200": { "$ref": "#/components/responses/GetDeviceKeyResponse" }, "400": { "$ref": "#/components/responses/ParameterValidationError" }, "401": { "$ref": "#/components/responses/GenericError" }, "403": { "$ref": "#/components/responses/GenericError" }, "404": { "$ref": "#/components/responses/GenericError" }, "500": { "$ref": "#/components/responses/GenericError" } } } } }, "components": { "schemas": { "deviceId": { "type": "string", "description": "Unique device identifier", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "example": "D123" }, "baseStationId": { "type": "string", "description": "Unique base station identifier", "example": "BST123", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "simId": { "type": "string", "description": "Unique SIM identifier", "example": "ADS123", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "patientId": { "type": "string", "description": "Unique patient identifier", "example": "PAT001", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "institutionId": { "type": "string", "description": "Unique organization / institution identifier", "example": "ORG001" }, "systemId": { "type": "string", "description": "Unique anonymized identifier of the patient. Random 16-byte hexadecimal sequence.", "example": "6bc7f4133779b08df8c", "pattern": "^[a-zA-Z0-9]{32}$" }, "firmwareVersion": { "type": "string", "description": "Version of the embedded firmware.", "example": "1.3.6", "pattern": "^(\\d+\\.)?(\\d+\\.)?(\\d+)$" }, "imei": { "type": "string", "description": "International Mobile Equipment Identifier", "example": "123ZAG7B9012BF5", "pattern": "^[a-zA-Z0-9]{15}$" }, "imeiRevision": { "type": "string", "description": "Version string of the IMEI hardware", "example": "1", "default": "1", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "serialNo": { "type": "string", "description": "Serial number of the physical PCB", "example": "394BASF", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "pcbRevision": { "type": "string", "description": "Version string of the PCB hardware", "example": "1", "default": "1", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "iccid": { "type": "string", "description": "ICCID of the physical SIM", "example": "394BASF", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "mvno": { "type": "string", "description": "MVNO of SIM", "example": "Verizon", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "dataProvider": { "type": "string", "description": "Data Provider of SIM", "example": "XLK", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "PaginationMetadataSchema": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "pageCount": { "type": "number", "example": 5 }, "itemsPerPage": { "type": "number", "example": 100 }, "total": { "type": "number", "example": 50 } }, "required": [ "page", "pageCount", "itemsPerPage", "total" ] } }, "requestBodies": { "PeerCertificateRequest": { "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string", "description": "Base64 encoded publicKey" } } }, "examples": { "PeerCertificateRequest": { "description": "Default use case.", "value": { "publicKey": "ENCODED_PEER_PUBKEY" } } } } } }, "CertificateExchangeRequest": { "content": { "application/json": { "schema": { "type": "object", "properties": { "csr": { "type": "string", "description": "Base64 encoded certificate signing request" } } }, "examples": { "CertificateSigningRequest": { "description": "Default use case.", "value": { "csr": "CSR" } } } } } }, "UpdateDeviceRequest": { "content": { "application/json": { "example": { "firmwareVersion": "A.0.9.2" }, "schema": { "type": "object", "required": [ "firmwareVersion" ], "properties": { "firmwareVersion": { "$ref": "#/components/schemas/firmwareVersion" } } } } } }, "AllocateKitRequest": { "content": { "application/json": { "example": { "institutionId": "ORG123" }, "schema": { "type": "object", "required": [ "institutionId" ], "properties": { "institutionId": { "$ref": "#/components/schemas/institutionId" } } } } } }, "PatientDevicesUpdateRequest": { "content": { "application/json": { "schema": { "type": "object", "required": [ "deviceId" ], "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" } } } } } }, "UpdateKitBaseStationRequest": { "content": { "application/json": { "schema": { "type": "object", "required": [ "baseStationId" ], "properties": { "baseStationId": { "$ref": "#/components/schemas/baseStationId" } } } } } }, "SwapBaseStationOnActiveKitRequest": { "content": { "application/json": { "schema": { "type": "object", "required": [ "newBaseStationId", "oldBaseStationId" ], "properties": { "oldBaseStationId": { "$ref": "#/components/schemas/baseStationId" }, "newBaseStationId": { "$ref": "#/components/schemas/baseStationId" } } } } } }, "UpdateKitSimRequest": { "content": { "application/json": { "schema": { "type": "object", "required": [ "simId" ], "properties": { "simId": { "$ref": "#/components/schemas/simId" } } } } } }, "SwapSimOnActiveKitRequest": { "content": { "application/json": { "schema": { "type": "object", "required": [ "oldSimId", "newSimId" ], "properties": { "oldSimId": { "$ref": "#/components/schemas/simId" }, "newSimId": { "$ref": "#/components/schemas/simId" } } } } } }, "RegisterSimRequest": { "description": "Sim Registration Request", "content": { "application/json": { "example": { "iccid": "SIMID1234", "mvno": "Verizon", "dataProvider": "XLK" }, "schema": { "type": "object", "required": [ "iccid", "mvno", "dataProvider" ], "properties": { "iccid": { "$ref": "#/components/schemas/iccid" }, "mvno": { "$ref": "#/components/schemas/mvno" }, "dataProvider": { "$ref": "#/components/schemas/dataProvider" } } } } } }, "DeviceRegisterRequest": { "description": "Device Registration Request", "content": { "application/json": { "example": { "firmwareVersion": "1.2.3", "serialNo": "AB34921CD", "pcbRevision": "1" }, "schema": { "type": "object", "properties": { "firmwareVersion": { "$ref": "#/components/schemas/firmwareVersion" }, "serialNo": { "$ref": "#/components/schemas/serialNo" }, "pcbRevision": { "$ref": "#/components/schemas/pcbRevision" } }, "required": [ "firmwareVersion", "serialNo" ] } } } }, "RegisterBaseStationRequest": { "content": { "application/json": { "example": { "certificate": "CERTIFICATE", "firmwareVersion": "0.2.2", "imei": "AB34921CD", "imeiRevision": "1" }, "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "Base-64 encoded MQTT certificate" }, "firmwareVersion": { "$ref": "#/components/schemas/firmwareVersion" }, "imei": { "$ref": "#/components/schemas/imei" }, "imeiRevision": { "$ref": "#/components/schemas/imeiRevision" } }, "required": [ "firmwareVersion", "imei" ] } } } }, "BaseStationUpdateRequest": { "content": { "application/json": { "example": { "certificate": "CERTIFICATE", "firmwareVersion": "0.2.2" }, "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "Base-64 encoded MQTT certificate" }, "firmwareVersion": { "$ref": "#/components/schemas/firmwareVersion" } } } } } }, "PrepareKitRequest": { "description": "Kit registration request", "content": { "application/json": { "example": { "simId": "ADS12345", "deviceId": "ADI12345", "baseStationId": "ADIBS12345" }, "schema": { "type": "object", "required": [ "deviceId", "baseStationId", "simId" ], "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "baseStationId": { "$ref": "#/components/schemas/baseStationId" }, "simId": { "$ref": "#/components/schemas/simId" } } } } } } }, "responses": { "GenericError": { "description": "Generics error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "ParameterValidationError": { "description": "Parameter validation error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "UpdateDeviceResponse": { "description": "Device update result", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "status": { "type": "string", "enum": [ "ok" ] }, "message": { "type": "string", "description": "Message indicating successful update" } } } } } }, "AllocateKitResponse": { "description": "Device-kit and institution link success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "institutionId": { "$ref": "#/components/schemas/institutionId" } } } } } }, "AllocateDeviceResponse": { "description": "Successful reposnse of the device assignment", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "patientId": { "$ref": "#/components/schemas/patientId" }, "systemId": { "$ref": "#/components/schemas/systemId" } } } } } }, "PatientAllocatedDeviceResponse": { "description": "Successful reposnse of the device assignment", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "patientId": { "$ref": "#/components/schemas/patientId" }, "systemId": { "$ref": "#/components/schemas/systemId" } } } } } }, "StatusResult": { "description": "Successful operation status response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates success of execution" } } } } } }, "DeviceRegisterResponse": { "description": "Successful operation status response", "content": { "application/json": { "example": { "id": "D123", "deviceKey": "QcSzC2vsjkC867aPjBS+fQ==", "deviceKeyId": "fa15241e", "peerCaPublicKey": "QcSzC2vsjkC867aPjBS+fQ==" }, "schema": { "type": "object", "properties": { "peerCaPublicKey": { "type": "string", "description": "Base-64 encoded peer-CA public key" }, "id": { "$ref": "#/components/schemas/deviceId" }, "deviceKey": { "type": "string", "description": "128-bit device key base64 encoded" }, "deviceKeyId": { "type": "string", "description": "CRC32 checksum for device key" } } } } } }, "RegisterBaseStationResponse": { "description": "Successful operation status response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/baseStationId" } } } } } }, "RegisterSimResponse": { "description": "Successful SIM registration response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/simId" } } } } } }, "PrepareKitResponse": { "description": "Successful kit registration response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "baseStationId": { "$ref": "#/components/schemas/baseStationId" }, "simId": { "$ref": "#/components/schemas/simId" } } } } } }, "GetSimResponse": { "description": "Successful SIM retreival response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/simId" }, "iccid": { "$ref": "#/components/schemas/iccid" }, "mvno": { "$ref": "#/components/schemas/mvno" }, "dataProvider": { "$ref": "#/components/schemas/dataProvider" } } } } } }, "BaseStationUpdateResponse": { "description": "Successful operation status response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/baseStationId" } } } } } }, "CertificateExchangeResponse": { "description": "Response with signed certificate", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "Base64 encoded X509 certificate", "example": "XXXXX" }, "caCertificate": { "type": "string", "description": "Base-64 encoded CA certificate" }, "mqttHostname": { "type": "string", "description": "IoT MQTT host to connect to" } } } } } }, "UpdateKitSimResponse": { "description": "Response of successful linking SIM to a kit", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "simId": { "$ref": "#/components/schemas/simId" } } } } } }, "UpdateKitBaseStationResponse": { "description": "Response with base station and device", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "baseStationId": { "$ref": "#/components/schemas/baseStationId" } } } } } }, "GetDeviceKeyResponse": { "description": "Successful operation status response", "content": { "application/json": { "example": { "status": "ok", "id": "ADI10001", "deviceKey": "QcSzC2vsjkC867aPjBS+fQ==" }, "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "id": { "$ref": "#/components/schemas/deviceId" }, "deviceKey": { "type": "string", "description": "128-bit device key base64 encoded", "example": "uLUymdKxe4/4+MYmWZTIAw==" }, "deviceKeyId": { "type": "string", "description": "32-bit device key identifier base64 encoded", "example": "12bb7acf" }, "active": { "type": "boolean", "example": true }, "firmwareVersion": { "$ref": "#/components/schemas/firmwareVersion" } } } } } }, "DeviceListResponse": { "description": "Response with devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/PaginationMetadataSchema" }, "items": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "firmwareVersion": { "$ref": "#/components/schemas/firmwareVersion" }, "serialNo": { "$ref": "#/components/schemas/serialNo" }, "pcbRevision": { "$ref": "#/components/schemas/pcbRevision" }, "baseStationId": { "example": "BST123", "oneOf": [ { "$ref": "#/components/schemas/baseStationId" }, { "type": "string" }, { "nullable": true } ] }, "simId": { "example": "ADS12345", "oneOf": [ { "$ref": "#/components/schemas/simId" }, { "type": "string" }, { "nullable": true } ] }, "institutionId": { "oneOf": [ { "$ref": "#/components/schemas/institutionId" }, { "type": "string" }, { "nullable": true } ] }, "patientId": { "oneOf": [ { "$ref": "#/components/schemas/patientId" }, { "type": "string" }, { "nullable": true, "example": null } ] } } } } } } } } }, "BaseStationListResponse": { "description": "Response with base stations", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "baseStationId": { "$ref": "#/components/schemas/baseStationId" }, "deviceId": { "example": "ADI10001", "oneOf": [ { "$ref": "#/components/schemas/deviceId" }, { "type": "string" }, { "nullable": true } ] }, "institutionId": { "example": "IN-02", "oneOf": [ { "$ref": "#/components/schemas/institutionId" }, { "type": "string" }, { "nullable": true } ] }, "patientId": { "example": "PT-1001", "oneOf": [ { "$ref": "#/components/schemas/patientId" }, { "type": "string" }, { "nullable": true, "example": null } ] }, "firmwareVersion": { "example": "1.80.1", "oneOf": [ { "$ref": "#/components/schemas/firmwareVersion" }, { "type": "string" }, { "nullable": true } ] }, "imei": { "$ref": "#/components/schemas/imei" }, "imeiRevision": { "$ref": "#/components/schemas/imeiRevision" }, "createdAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the base station has been created" }, "updatedAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the base station has been updated" } } } }, "metadata": { "$ref": "#/components/schemas/PaginationMetadataSchema" } } } } } }, "ListSimsResponse": { "description": "Response of listing SIMs", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/PaginationMetadataSchema" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/simId" }, "iccid": { "$ref": "#/components/schemas/iccid" }, "mvno": { "$ref": "#/components/schemas/mvno" }, "dataProvider": { "$ref": "#/components/schemas/dataProvider" }, "createdAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the base station has been created" }, "updatedAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the base station has been updated" } } } } } } } } }, "ListKitsResponse": { "description": "Response with devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/PaginationMetadataSchema" }, "items": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "baseStationId": { "example": "ADIBST123", "oneOf": [ { "$ref": "#/components/schemas/baseStationId" }, { "type": "string" }, { "nullable": true } ] }, "simId": { "example": "ADS12345", "oneOf": [ { "$ref": "#/components/schemas/simId" }, { "type": "string" }, { "nullable": true } ] }, "institutionId": { "example": "IN-023", "oneOf": [ { "$ref": "#/components/schemas/institutionId" }, { "type": "string" }, { "nullable": true } ] }, "patientId": { "example": "PT-123", "oneOf": [ { "$ref": "#/components/schemas/patientId" }, { "type": "string" }, { "nullable": true } ] }, "createdAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the link has been created" }, "updatedAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the link has been updated" } } } } } } } } }, "DeactivateKitResponse": { "description": "Response with device identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" } } } } } }, "UnlinkBaseStationResponse": { "description": "Response with base station and device", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "baseStationId": { "$ref": "#/components/schemas/baseStationId" } } } } } }, "UnlinkSimResponse": { "description": "Response to successfully unlinking SIM from kit", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "$ref": "#/components/schemas/deviceId" }, "simId": { "$ref": "#/components/schemas/simId" } } } } } }, "BaseStationLinksResponse": { "description": "Response with base station and device", "content": { "application/json": { "schema": { "type": "object", "properties": { "baseStationId": { "$ref": "#/components/schemas/baseStationId" }, "simId": { "oneOf": [ { "$ref": "#/components/schemas/simId" }, { "type": "string" }, { "nullable": true } ] }, "deviceId": { "oneOf": [ { "$ref": "#/components/schemas/deviceId" }, { "type": "string" }, { "nullable": true } ] }, "institutionId": { "oneOf": [ { "$ref": "#/components/schemas/institutionId" }, { "type": "string" }, { "nullable": true } ] } } } } } }, "PeerCertificateResponse": { "description": "Response of signed peer-certificate", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "Base64 encoded peer certificate", "example": "XXXXX" }, "expiration": { "type": "integer", "description": "Unix timestamp of cert expiration in seconds", "example": 1593144240 } } } } } }, "BaseStationDetailsResponse": { "description": "Response with base station details", "content": { "application/json": { "schema": { "type": "object", "properties": { "baseStationId": { "$ref": "#/components/schemas/baseStationId" }, "deviceId": { "example": "ADI10001", "oneOf": [ { "$ref": "#/components/schemas/deviceId" }, { "type": "string" }, { "nullable": true } ] }, "simId": { "example": "ADS12345", "oneOf": [ { "$ref": "#/components/schemas/simId" }, { "type": "string" }, { "nullable": true } ] }, "institutionId": { "example": "IN-02", "oneOf": [ { "$ref": "#/components/schemas/institutionId" }, { "type": "string" }, { "nullable": true } ] }, "patientId": { "example": "PT-1001", "oneOf": [ { "$ref": "#/components/schemas/patientId" }, { "type": "string" }, { "nullable": true, "example": null } ] }, "firmwareVersion": { "example": "1.80.1", "oneOf": [ { "$ref": "#/components/schemas/firmwareVersion" }, { "type": "string" }, { "nullable": true } ] }, "imei": { "$ref": "#/components/schemas/imei" }, "imeiRevision": { "$ref": "#/components/schemas/imeiRevision" }, "createdAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the base station has been created" }, "updatedAt": { "type": "string", "format": "date", "example": "2020-10-08T20:13:14.000Z", "description": "Indicated when the base station has been updated" } } } } } } }, "parameters": { "DeviceId": { "name": "deviceId", "in": "path", "required": true, "example": "D123", "description": "Unique device identifier", "schema": { "$ref": "#/components/schemas/deviceId" } }, "BaseStationId": { "name": "baseStationId", "in": "path", "required": true, "example": "BST123", "description": "Unique base station identifier", "schema": { "$ref": "#/components/schemas/baseStationId" } }, "SimId": { "name": "simId", "in": "path", "required": true, "example": "ADS12345", "description": "Unique SIM identifier", "schema": { "$ref": "#/components/schemas/simId" } }, "PatientId": { "name": "patientId", "in": "path", "example": "PAT123", "description": "Unique patient identifier", "required": true, "schema": { "$ref": "#/components/schemas/patientId" } }, "SearchQueryParam": { "name": "term", "in": "query", "required": false, "example": "ADI", "schema": { "type": "string", "default": "" }, "description": "Optional search request parameter for list-based requests that support it." }, "PageNumberQueryParam": { "name": "page", "in": "query", "required": false, "schema": { "type": "number", "default": 1, "minimum": 1 }, "description": "Page number. Starts from 1." }, "ItemsPerPageQueryParam": { "name": "itemsPerPage", "in": "query", "required": false, "schema": { "type": "number", "minimum": 2, "maximum": 1000, "default": 100 }, "description": "Optional pagination parameter for list-based requests that support it" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } } } }