Hubs

A hub is the 1key device in a building that controls its locks, thermostats, switches and sensors. Each hub has a hub ID printed on its label, such as 1key-xfy2-nmf4-5xwp.

Adding a hub

Each hub is at one of your organization's sites. Once a hub is installed and online, add it to a site by the Serial on its label:

curl -X POST https://api.1keyplatform.dev/v1/hubs \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serial": "1KEY-XFY2-NMF4-5XWP", "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40", "name": "Lobby hub"}'

Needs hubs:write. The Serial is accepted in any case, with or without dashes. From then on the hub appears in GET /hubs. The portal does the same.

A hub belongs to one organization at a time: the first to add it keeps it. 422 hub_not_addable means the Serial is unknown, the hub has not come online yet, or another organization has it. Adding a hub your organization already has moves it to the site you name.

Reading hubs

curl https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

{
  "id": "1key-xfy2-nmf4-5xwp",
  "name": "Lobby hub",
  "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40",
  "connection": {
    "status": "online",
    "since": "2026-10-01T09:14:02Z",
    "public_ip": "203.0.113.7",
    "disconnect_reason": null
  },
  "firmware": { "version": "0.4.2" },
  "network": {
    "type": "wifi",
    "interface": "wlan0",
    "ip_address": "192.168.1.40",
    "ipv6_address": null,
    "mac_address": "b8:27:eb:12:34:56",
    "ssid": "Lobby",
    "signal_dbm": -61,
    "carrier": null,
    "radio": null,
    "metered": false,
    "reported_at": "2026-10-01T09:14:03Z"
  },
  "registered_at": "2026-09-12T15:30:00Z"
}

connection.status is online or offline as AWS IoT sees the hub's connection, or unknown when the hub has not connected since it was added. hub.connected and hub.disconnected events report changes.

firmware and network are what the hub reported when it last connected, and null until it does. network.type is wifi, ethernet or cellular.

A hub that is not your organization's returns 404, the same as one that does not exist.

Devices

A hub's devices are read and commanded live through the hub. See devices and commands.

Listing hubs

GET /hubs lists your hubs by hub ID, 50 to a page; pass the last hub's id as starting_after for the next. Add site_id to list one site's hubs.

Resetting a hub's link

A hub that was factory reset, or lost its key, can't reconnect with its old certificate. Reset its link and it requests a new certificate on its own:

curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/reset-link \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

A hub that was refused retries every six hours, so it reconnects within six hours, or at once if you restart it. It stays in your organization, at its site. Needs hubs:write.

Renaming and moving

curl -X PATCH https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lobby hub", "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40"}'

Send name, site_id or both. A null name clears it. Needs hubs:write.