1KEY Developers
API reference

SmartStart

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.

SmartStart

Devices that join on their own when powered on, from their QR codes. Codes for a hub that is offline, or has never connected, are kept until it connects.

GET /hubs/{hub_id}/setup-codes

List the hub's SmartStart codes

Needs the hubs:read scope.

Every code on the hub's SmartStart list, and the changes to it the hub hasn't confirmed yet, newest first. An online hub is read first; an offline hub's list is the cloud's copy, as of synced_at.

Parameters

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

Responses

200 The hub's codes.

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.
POST /hubs/{hub_id}/setup-codes

Add a device's SmartStart code

Needs the hubs:write scope.

Puts a device's SmartStart QR code on the hub's list. The device joins on its own whenever it's powered on, taking name and room. An online hub is told now (201). An offline hub, or one that has never connected, is told when it connects (202, state queued). Adding a code already on the list replaces its name, room and network.

Only SmartStart codes (QR version 01) are taken. A device with an S2-only code is added with POST /hubs/{hub_id}/pairing.

Parameters

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

Body

code string · required The QR code's text: 90 followed by its digits. Never returned.
name string or null · optional The name the device takes when it joins.
network "long_range" | "mesh" · optional How a device that can join over Long Range does. Omitted: Long Range. mesh keeps it on the mesh, for a device that has to reach the hub through repeaters.
room string or null · optional

Responses

201 On the hub's list. · returns a SetupCode
202 Queued until the hub connects. · returns a SetupCode

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.
DELETE /hubs/{hub_id}/setup-codes/{setup_code_id}

Remove a code from the hub's list

Needs the hubs:write scope.

The device is no longer admitted when it powers on. A device that already joined from the code stays on the network until it is removed or reset: device_id names it.

Parameters

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

Responses

200 Removed, or queued for the hub.

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}/setup-codes/{setup_code_id}

Rename a code before its device joins

Needs the hubs:write scope.

Sets the name and room the device takes when it joins. Once it has joined, rename the device instead.

Parameters

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

Body

name string or null · optional
room string or null · optional

Responses

200 Updated on the hub. · returns a SetupCode
202 Queued until the hub connects. · returns a SetupCode

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.
POST /hubs/{hub_id}/setup-codes/{setup_code_id}/restore

Put a missing code back on the hub

Needs the hubs:write scope.

A missing code (dropped by a network reset, or removed at the hub) goes back on the hub's list, now or when it connects.

Parameters

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

Responses

200 Back on the hub's list. · returns a SetupCode
202 Queued until the hub connects. · returns a SetupCode

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.