DeviceAuth

Description

Using the device module enforces a more strict connection process for devices. By curating a list of public keys for each device, we issue a challenge that the device has to sign with the corresponding private key. Once successful, the device is allowed to connect to the backend. Any other device will not be allowed to connect to the backend anymore.

Events

Following events are transmitted via the websocket.

DEVICE_AUTH_UPDATE

This event will be sent over the websocket, should any information regarding the device auth change. This event requires read access to the resource deviceAuth.

Name	Description
type stringconstant	Constant value: DEVICE_AUTH_UPDATE
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
publicKey stringoptional	The public key that will be used to verify the challenge that the device returned.
unknown boolean	Whenever the device is known to the backend or not. `Known` means it has a valid public key set in this module and the challenge response authentication was successful. An invalid public key will also lead for the `unknown` property to be true.

API

Endpoints

POST

Upload CSV device access list

GET

Get device access list

DEL

Clear device access list

POST

Set single device access

GET

Get single device access

DEL

Clear single device access

Upload CSV device access list

This endpoint can be used to upload a .csv-file to create or update device access. The first column of this file are the device identifier, while the second column represents the public key.
Therefore, every row should have two entries containing the device identifier and public key pair, preferably divided by a semicolon. A one row example of the .csv-file would look like the following:

809212389122821;Sm80K2RKZjByemJhMG04aAozdTJTa2Y3Z3BKckxacDU1QmRRMEl4WUNpT1ZCUUd4a25yYjVZY1haQ3J5UTZPd0MvR3UwZLS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUVqeWZ3dGNGUmdBRHNGd1c2Gc9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0K

The public key is represented in base64 format.

POST

/api/v1/deviceauth

Access

This endpoint requires update permission for the resource deviceAuth.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get device access list

Returns the list of all devices that have a known public key and devices that tried to connect without.

GET

/api/v1/deviceauth

Access

This endpoint requires read permission for the resource deviceAuth.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
information objectoptional	Information to authenticate the device.
information.publicKey stringoptional	The public key that will be used to verify the challenge that the device returned.
information.unknown boolean	Whenever the device is known to the backend or not. `Known` means it has a valid public key set in this module and the challenge response authentication was successful. An invalid public key will also lead for the `unknown` property to be true.

Clear device access list

Sets all devices to be of type unknown and resets the public key.

DELETE

/api/v1/deviceauth

Access

This endpoint requires delete permission for the resource deviceAuth.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Set single device access

Updates the access information for a single device.

POST

/api/v1/deviceauth/:deviceIdentifier

Access

This endpoint requires update permission for the resource deviceAuth.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Request Body

Name	Description
publicKey string	The public key that will be used to verify the challenge that the device returned.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get single device access

Returns access information in the form of the public key for a single device.

GET

/api/v1/deviceauth/:deviceIdentifier

Access

This endpoint requires read permission for the resource deviceAuth.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Response

Name	Description
publicKey stringoptional	The public key that will be used to verify the challenge that the device returned.
unknown boolean	Whenever the device is known to the backend or not. `Known` means it has a valid public key set in this module and the challenge response authentication was successful. An invalid public key will also lead for the `unknown` property to be true.

Clear single device access

Removes the public key for a single device.

DELETE

/api/v1/deviceauth/:deviceIdentifier

Access

This endpoint requires delete permission for the resource deviceAuth.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.