Get started

Quickstart

Unlock a door through one of your hubs. You need an API key with the hubs:read and hubs:command scopes.

Create an API key

Create a key on the API keys page and store it as an environment variable on your server. Every request sends it as a bearer token.

export ONEKEY_API_KEY="1key_live_…"

List your hubs

Ask for the hubs your organization owns.

curl https://api.1keyplatform.dev/v1/hubs \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

const res = await fetch("https://api.1keyplatform.dev/v1/hubs", {
  headers: { Authorization: `Bearer ${process.env.ONEKEY_API_KEY}` },
});
const { data: hubs } = await res.json();

import os, requests

res = requests.get(
    "https://api.1keyplatform.dev/v1/hubs",
    headers={"Authorization": f"Bearer {os.environ['ONEKEY_API_KEY']}"},
)
hubs = res.json()["data"]

hubs =
  Req.get!("https://api.1keyplatform.dev/v1/hubs",
    auth: {:bearer, System.fetch_env!("ONEKEY_API_KEY")}
  ).body["data"]

json

{
  "data": [
    {
      "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 },
      "registered_at": "2026-09-12T15:30:00Z"
    }
  ],
  "has_more": false
}

Find the lock

List the hub's devices and find the one with a writable lock channel.

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

{
  "data": [
    {
      "id": 7,
      "name": "Front door",
      "manufacturer": "Yale",
      "model": "YRD256",
      "channels": [
        { "key": "lock", "endpoint": 0, "kind": "lock", "writable": true, "available": true, "unit": null, "readable": true, "capabilities": {} }
      ]
    }
  ]
}

curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/commands \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"key": "lock", "value": false}'

const res = await fetch("https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/commands", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ONEKEY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ key: "lock", value: false }),
});
const command = await res.json();

import uuid

command = requests.post(
    "https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/commands",
    headers={
        "Authorization": f"Bearer {os.environ['ONEKEY_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"key": "lock", "value": False},
).json()

command =
  Req.post!("https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/commands",
    auth: {:bearer, System.fetch_env!("ONEKEY_API_KEY")},
    headers: [{"idempotency-key", Ecto.UUID.generate()}],
    json: %{key: "lock", value: false}
  ).body

202 means the hub accepted it: the channel's status is pending. When the lock reports back, a channel.observed event arrives and the channel's status becomes synchronized.

Next steps

Events: see the lock report back, and every other change, as it happens.
Devices: channels and what each one takes.
Errors: what each status means for a hub command.
API reference: every endpoint, from the OpenAPI spec.