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 -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" }]
}'
{
"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 |