1KEY Developers
API reference

Setup

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.

Setup

Checking a device works before marking its setup complete. The hub runs the checks and keeps the mark.

POST /hubs/{hub_id}/devices/{device_id}/setup/{action}

Test, fix, or complete a device's setup

Needs the hubs:write scope.

Action Does
ping Asks the device to answer; the reachable check records it
identify The device blinks or beeps. Needs hubs:command instead of hubs:write
interview The hub learns what the device is again, from the start
repair_reporting Points the device's reports at the hub
rebuild_routes Finds the device fresh routes to the hub
test Starts the device's test on the hub (202): a writable channel goes to another value and back, and each must be reported; a device with nothing to write must report something within two minutes. A lock or barrier is moved only with person_present: true; otherwise it is asked to report its state. device.setup_test_step and device.setup_tested events follow. Needs hubs:command too
complete Marks setup complete; refused until every required check passes. The answer is the device
reopen Puts the device back into setup. The answer is the device

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer
action required path "ping" | "identify" | "interview" | "repair_reporting" | "rebuild_routes" | "test" | "complete" | "reopen"

Body

person_present boolean, default false · optional For test: someone is at the device, so the test may unlock and lock a lock, or open and close a barrier. Send true only after they confirm.

Responses

200 Done.
202 The test started.

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.
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}/devices/{device_id}/setup

A device's setup checks

Needs the hubs:read scope.

The hub runs the checks and keeps their results. Setup can be marked complete once every required check has passed; advisory checks only warn. Each check lists the actions that fix or test it.

Parameters

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

Responses

200 The device's setup. · returns a DeviceSetup

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.
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.