1KEY Developers
API reference

Hubs

Base URL https://api.1keyplatform.dev/v1. Every endpoint below is generated from the OpenAPI contract, which you can download as openapi.yaml.

Log in to send these requests to your organization from this page.

Hubs

Hubs your organization owns.

GET /hubs/{hub_id}/logs

Read a hub's logs

Needs the hubs:read scope.

The hub's most recent log lines (firmware, radio, network), oldest first, read live from the hub. See logs and black box.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
lines optional query integer, 1–500, default 200 How many lines, 1 to 500. Default 200.

Responses

200 The log.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
POST /hubs/{hub_id}/actions/{action}

Run a recovery action on a hub

Needs the hubs:write scope.

The hub answers, then acts two seconds later. See recovery actions.

Only an owner or admin may reboot or zwave_restart: a key whose creator is a member gets 403 forbidden.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
action required path "repair_lifeline" | "zwave_restart" | "reboot" | "network_reconnect" repair_lifeline points a device's Lifeline association, and the groups its product needs, at the hub: for a device that works when commanded but never reports changes. zwave_restart restarts the hub's Z-Wave radio program, a few seconds without Z-Wave. reboot reboots the hub, offline for about a minute. network_reconnect re-applies the hub's network configuration; its link drops and comes back.

Body

device_id integer · optional The device, for repair_lifeline; required there.

Responses

202 The hub took the action.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 forbidden The key lacks the operation's scope (insufficient_scope), or acts with its creator's role (forbidden): only owners' and admins' keys manage members and invitations, and no key changes, removes or makes an owner.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/radio

Read a hub's Z-Wave radio

Needs the hubs:read scope.

The hub's Z-Wave radio as the radio reports it, read live from the hub. The fields follow the radio and may change with the hub's firmware; a value the radio can't give is null. Devices are named by device_id. See Z-Wave diagnostics.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

200 The radio.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
PUT /hubs/{hub_id}/sim/auto-activate

Turn a hub's cellular auto-activate on or off

Needs the hubs:write scope.

The cloud keeps a hub's SIM inactive until the hub needs cellular, then activates it. Turned off, the SIM is never activated, for example for a hub in stock. Works for a hub that hasn't reported a SIM yet. See cellular.

Only an owner or admin may: a key whose creator is a member gets 403 forbidden.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

enabled boolean · required

Responses

200 Auto-activate as it now is.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 forbidden The key lacks the operation's scope (insufficient_scope), or acts with its creator's role (forbidden): only owners' and admins' keys manage members and invitations, and no key changes, removes or makes an owner.
404 not_found No such resource, or it is not your organization's.
POST /hubs/{hub_id}/wifi/networks

Save a Wi-Fi network on a hub

Needs the hubs:write scope.

Saves a network on the hub, or changes a saved one. A new network goes last unless priority places it; a saved one keeps its place and, without password, its password. The hub saves the change when it answers and applies it seconds later. Saving a network the hub is holding out ends the hold. See Wi-Fi.

Only an owner or admin may: a key whose creator is a member gets 403 forbidden.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

ssid string, up to 32 characters · required
password string · optional 8 to 63 printable characters, or 64 hex digits; the network is saved as WPA2, which a WPA3-only access point doesn't take. Without it a saved network keeps its own and a new one is saved as open. Sent only to the hub, never stored or logged by the cloud.
priority integer, at least 1 · optional Its place in the order the hub tries networks, 1 first. A place past the end means last.

Responses

200 The saved networks, with the change. · returns a WifiNetworks

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
POST /hubs/{hub_id}/network-check

Check a hub's network

Needs the hubs:read scope.

The hub checks each of its network interfaces out to the cloud: its link, DHCP, gateway, DNS, the internet, the ports and TLS it connects with, path MTU, MQTT and time. It answers with what it measured and findings, each with a message and a fix for whoever installs the hub. Takes up to 20 seconds, or 75 with trace or wifi_scan. The result is kept as the hub's connection.network_check. See network checks.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

count integer, 1–20, default 5 · optional Probes per measured step.
interfaces array of string · optional Only these interfaces. Default every interface the hub has.
trace boolean, default false · optional Trace the route to the cloud from each interface.
wifi_scan boolean, default false · optional List the Wi-Fi networks the hub can see.

Responses

200 The check's result.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/health

Read a hub's health

Needs the hubs:read scope.

The hub's own health, read live from the hub. A field the hub can't read is null. See health.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

200 The hub's health.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/uptime

Get a hub's uptime

Needs the hubs:read scope.

When the hub was connected to the cloud, from the sessions the cloud records (kept 35 days). 24h is the last 24 hours; 7d and 30d start at midnight 6 or 29 days ago in the site's time zone, so days are whole local days. Time before the cloud's first record of the hub is unknown and left out of uptime_pct. See uptime.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
range optional query "24h" | "7d" | "30d" The window. Default 24h.

Responses

200 The hub's uptime. · returns a Uptime

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /hubs/{hub_id}/black-box

Read a hub's black box

Needs the hubs:read scope.

What the hub keeps across reboots, read live from the hub. previous is what it recorded before its last reboot (alarms, memory, the log tail); boots is one line per boot with its cause; panic is the last kernel panic. 404 when the hub has no such recording. See logs and black box.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
which optional query "previous" | "boots" | "panic" The recording. Default previous.

Responses

200 The recording.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/wifi

List a hub's saved Wi-Fi networks

Needs the hubs:read scope.

The Wi-Fi networks saved on the hub, in the order it tries them, read live from the hub. Passwords are never returned. See Wi-Fi.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

200 The saved networks. · returns a WifiNetworks

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs

List hubs

Needs the hubs:read scope.

Hubs your organization owns, ordered by hub ID, or with sort=attention problems first: offline, then never heard from, then the rest, each by hub ID. Pass next_cursor as cursor for the next page of either order.

Parameters

Name In Type Description
limit optional query integer, 1–100, default 50
starting_after optional query string ID of the last item on the previous page.
cursor optional query string next_cursor from the page before, in the same sort. Not with starting_after.
sort optional query "hub_id" | "attention" hub_id (default), or attention: offline hubs first, then hubs never heard from, then the rest.
site_id optional query string Only hubs at this site.
status optional query "online" | "offline" | "unknown" Only hubs with this connection status.
kind optional query "ethernet" | "wifi" | "cellular" | "offline" | "never" | "online" Only hubs of this kind; online for ethernet, wifi and cellular.
issue optional query "offline" | "crash" | "blocked" | "weak" | "nobackup" | "never" | "unchecked" Only hubs that need attention for this reason: offline, or never heard from, or one of the flags.
issue_site optional query string Only hubs at this site. Used with issue for one site's share of it.
include_test optional query boolean, default true Whether hubs at test sites are listed. A site_id lists its own hubs either way.
q optional query string Only hubs whose ID, name or site name contains this, ignoring case.

Responses

200 A page of hubs.
200 · example
{
  "data": [
    {
      "connection": {
        "since": "2026-10-01T09:14:02Z",
        "status": "online"
      },
      "crashes_7d": 0,
      "flags": [
        "weak"
      ],
      "id": "1key-xfy2-nmf4-5xwp",
      "kind": "wifi",
      "name": "Lobby hub",
      "registered_at": "2026-09-12T15:30:00Z",
      "registered_by": {
        "email": "[email protected]",
        "id": "3b0e6d1a-77c2-4f0e-8d1b-5a2c9e4f6a10"
      },
      "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40",
      "site_name": "120 King St"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
429 Too many requests. Retry after the Retry-After header.
POST /hubs

Add a hub to a site

Needs the hubs:write scope.

Adds a hub to one of your sites by the Serial on its label. The hub must be installed and online. The first organization to add a hub keeps it. Adding a hub your organization already has moves it to the given site.

Body

serial string · required The Serial on the hub's label, in any case, with or without dashes.
site_id string · required
name string or null · optional

Responses

200 The hub, now at the site. · returns a Hub

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
422 hub_not_addable The hub can't be added. The Serial is unknown, the hub has not come online, or another organization has it.
GET /hubs/{hub_id}/sim/events

List a hub's SIM events

Needs the hubs:read scope.

KORE's attach and data-session events for the hub's SIM, newest first, kept 30 days. KORE's own traffic to the SIM (sessions on its ota.* APN) is left out. See cellular.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
limit optional query integer, 1–100, default 25 How many, 1 to 100. Default 25.
offset optional query integer, at least 0, default 0 How many of the newest to skip. Default 0.

Responses

200 A page of events.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
PUT /hubs/{hub_id}/wifi/order

Reorder a hub's saved Wi-Fi networks

Needs the hubs:write scope.

Sets the order the hub tries its saved networks in. ssids must name every saved network exactly once.

Only an owner or admin may: a key whose creator is a member gets 403 forbidden.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

ssids array of string · required

Responses

200 The saved networks, with the change. · returns a WifiNetworks

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/wifi/scan

Scan for Wi-Fi networks near a hub

Needs the hubs:read scope.

The hub scans and lists the Wi-Fi networks it can see, without leaving the network it is on. Hidden networks aren't listed; save one by its name. Takes a few seconds. See Wi-Fi.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

200 The networks in range.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
DELETE /hubs/{hub_id}/wifi/networks/{ssid}

Remove a saved Wi-Fi network from a hub

Needs the hubs:write scope.

Removes the network. The hub saves the change when it answers. An unknown network answers not_found; a hub whose Wi-Fi is busy answers hub_unavailable, which can be retried.

Only an owner or admin may: a key whose creator is a member gets 403 forbidden.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
ssid required path string The network's name, URL-encoded.

Responses

200 The saved networks, with the change. · returns a WifiNetworks

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/sim

Get a hub's SIM

Needs the hubs:read scope.

The cellular SIM the hub last reported, what KORE says of it, and whether the cloud activates it when the hub needs cellular. 404 when the hub has reported no SIM. See cellular.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
refresh optional query boolean, default false true reads the SIM's status and usage from KORE first. Usage is read at most every 5 minutes.
expand optional query "tower" tower includes where OpenCelliD places the SIM's cell, which may look it up.

Responses

200 The SIM. · returns a Sim

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /hubs/{hub_id}/audit

Read a hub's audit log

Needs the hubs:read scope.

What was done on the hub, newest first, read live from the hub: devices added or forgotten, credentials, resets, reboots and repairs. Page back with before, the last entry's id. See audit log.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
limit optional query integer, 1–100, default 50 How many entries, 1 to 100. Default 50.
before optional query integer, at least 1 Only entries with a lower id.

Responses

200 A page of entries.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
DELETE /hubs/{hub_id}

Remove a hub

Needs the hubs:write scope.

Removes the hub from your organization and the cloud, so a hub that was factory reset can start over: its certificates and its AWS IoT thing are deleted, and so is everything recorded about it (events, sessions, uptime, alarms, connection, setup codes, deployments). Organization and site totals keep its past. Its SIM stays on the account and is set inactive. confirm must repeat the hub's ID.

The hub can't reconnect afterwards. Factory reset it and add it again by its Serial (POST /hubs) once it has requested a new certificate; adding it lets its SIM be activated again. A hub.deleted signal goes out on the event streams. Owners and admins only (403 forbidden).

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

confirm string · required The hub's ID.

Responses

204 Removed.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
500 AWS IoT refused part of the removal. The hub is still in your organization; try again.
GET /hubs/{hub_id}

Get a hub

Needs the hubs:read scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
expand optional query "devices" devices includes the hub's devices, read live. A hub that can't answer still returns, with devices null and devices_error saying why.

Responses

200 The hub. · returns a Hub
200 · example
{
  "connection": {
    "since": "2026-10-01T09:14:02Z",
    "status": "online"
  },
  "id": "1key-xfy2-nmf4-5xwp",
  "name": "Lobby hub",
  "registered_at": "2026-09-12T15:30:00Z",
  "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40"
}

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
PATCH /hubs/{hub_id}

Update a hub

Needs the hubs:write scope.

Renames the hub, moves it to another of your sites, or both.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

name string or null · optional Display name. null clears it.
site_id string · optional Move the hub to this site.

Responses

200 The updated hub. · returns a Hub

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.