1KEY Developers
Guides

Access

Access

Who can open a lock: users, each with credentials (PINs or cards) and an optional schedule. The hub keeps them and writes each credential to the lock when its schedule allows, and clears it when it doesn't, in the site's time zone, even while the hub is offline from the cloud. A credential's code is sent once and never returned.

Adding someone

One call creates the user and their credentials:

curl
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/users \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Unit 402 cleaner",
    "schedule": {
      "starts_at": "2026-10-12T00:00:00-04:00",
      "ends_at": "2027-01-01T00:00:00-05:00",
      "weekly": [{ "days": ["mon", "thu"], "from": "09:00", "to": "13:00" }]
    },
    "credentials": [{ "kind": "pin", "code": "482915" }]
  }'
json
{
  "id": 4,
  "device_id": 7,
  "label": "Unit 402 cleaner",
  "type": "general",
  "enabled": true,
  "schedule": {
    "starts_at": "2026-10-12T00:00:00-04:00",
    "ends_at": "2027-01-01T00:00:00-05:00",
    "weekly": [{ "days": ["mon", "thu"], "from": "09:00", "to": "13:00" }]
  },
  "credentials": [
    { "id": 12, "slot": 3, "kind": "pin", "state": "pending", "applied": false }
  ]
}
Field
label required 1–100 characters: who or what it's for
type optional general (default), disposable (one use), non_access (recorded, never opens)
enabled optional false suspends every credential without deleting it
schedule optional null or absent: always. starts_at/ends_at (ISO 8601 with offset) bound it; weekly periods (days from mon…sun, from/to as HH:MM in the site's time zone) narrow it. A weekly schedule needs the site's time zone: without it the hub refuses it with 400 "a weekly schedule needs the site's time zone (hub.time_zone)"
credentials optional Each {kind?, code, slot?}: kind is pin (default) or card, and code is 4–10 digits. Without slot, the hub picks the lowest free one. If the lock refuses one, the user isn't kept and the error names it

A request is checked strictly before it reaches the hub: an unknown field, a value of the wrong type, a time without an offset or a period with an unknown day is refused with 400 naming the field. Needs hubs:write. The lock must have joined securely enough to be driven; otherwise 422 command_refused.

A credential's state

state
pending Created, or outside its schedule; the lock hasn't confirmed it yet
active The lock confirmed it holds the code
expired Its schedule ended and the lock confirmed the slot is clear
revoked Revoked; applied turns true once the lock confirms

applied is whether the lock holds what state says; the hub checks every 30 seconds.

Changing and removing

Request
GET /hubs/{hub_id}/devices/{device_id}/users The lock's users and their credentials. Needs hubs:read
PATCH …/users/{user_id} label, type, enabled, schedule; "schedule": null makes it always. Credentials are added and revoked on their own routes. Answers the user as GET lists it
DELETE …/users/{user_id} Removes the user and clears their credentials from the lock: a credential.revoked event for each credential not already revoked, then user.deleted
POST …/users/{user_id}/credentials Adds a credential: {kind?, code, slot?}
DELETE …/users/{user_id}/credentials/{credential_id} Revokes one now

When the lock is full

A slot is free when no credential holds it, or only a revoked one. A credential without slot on a lock with none free is refused with 409 slots_full; revoke a credential to free its slot. A slot that is taken is refused with 400.

Events

Type
user.created, user.updated, user.deleted A user changed: the user's fields, or {user_id, label} when deleted
credential.created, credential.applied, credential.revoked A credential changed, or the lock confirmed it; data names it by credential_id. Deleting a user revokes each of its credentials
credential.used {device_id, user_id, credential_id, slot, method}: someone opened the lock with it; method is keypad, rfid or biometric
credential.rejected {device_id, method, event}: the lock refused a credential
credential.diverged {credential_id, reported}: the lock reports something other than what was confirmed
credential.replaced {credential_id, slot}: a new credential took over the slot of this revoked or expired one