Devices API

These endpoints cover the full device lifecycle, from initial registration through credential rotation and revocation.

Base URL: https://api.hestialabs.in/v1

Endpoints

Method	Path	Summary
GET	/devices	List Devices
GET	/devices/{id}	Get Device
POST	/device/{id}/revoke	Revoke Device
POST	/device/{id}/rotate-secret	Rotate Device Secret
POST	/device/register	Register Device

List Devices

GET /devices

List all devices for the tenant

Authentication: Bearer JWT required

Parameters

None.

Responses

Status	Description
200	Device list

Example 200 response

{
  "devices": [
    {}
  ],
  "count": 0
}

Get Device

GET /devices/{id}

Get device details by ID

Authentication: Bearer JWT required

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	—

Responses

Status	Description
200	Device info
404	Device not found

Example 200 response

{
  "device": {}
}

Revoke Device

POST /device/{id}/revoke

Revoke a device and add to blacklist

Authentication: Bearer JWT required

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	—

Responses

Status	Description
200	Device revoked

Example 200 response

{
  "device_id": "string",
  "status": "revoked"
}

Rotate Device Secret

POST /device/{id}/rotate-secret

Rotate device key and get new secret (24h dual-key grace window)

Authentication: Bearer JWT required

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	—

Responses

Status	Description
200	Secret rotated

Example 200 response

{
  "device_id": "string",
  "new_secret": "string",
  "key_version": 0
}

Register Device

POST /device/register

Register a new device and get its secret

Authentication: Bearer JWT required

Parameters

None.

Request body

Field	Type	Required	Description
device_type	string	Yes	Device type (e.g., smart-sensor, smart-switch)
home_id	string	Yes	Home UUID to assign device to
room_id	string	No	Optional room UUID

Example request

{
  "device_type": "string",
  "home_id": "string",
  "room_id": "string"
}

Responses

Status	Description
201	Device registered
403	Forbidden
503	Beta limit reached

Example 201 response

{
  "status": "string",
  "device_id": "string",
  "tenant_id": "string",
  "device_secret": "string",
  "initial_sequence": 0,
  "api_base_url": "string"
}