1KEY Developers
API reference

Access

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.

Access

Lock users, their PINs and cards, and the schedules the hub enforces.

DELETE /hubs/{hub_id}/devices/{device_id}/users/{user_id}

Remove a user and clear their credentials

Needs the hubs:write scope.

Parameters

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

Responses

204 Removed.

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.
422 command_refused The hub refused the command, for example a lock that did not join securely enough to be driven.
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.
PATCH /hubs/{hub_id}/devices/{device_id}/users/{user_id}

Change a user's label, type, enabled or schedule

Needs the hubs:write scope.

Parameters

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

Body

enabled boolean · optional
label string, up to 100 characters · optional
schedule AccessSchedule or null · optional
type "general" | "disposable" | "non_access" · optional

Responses

200 Updated. · returns a LockUser

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.
422 command_refused The hub refused the command, for example a lock that did not join securely enough to be driven.
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.
POST /hubs/{hub_id}/devices/{device_id}/users/{user_id}/credentials

Add a credential to a user

Needs the hubs:write scope.

Parameters

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

Body

code string · required 4–10 digits, for a PIN or a card. Never returned.
kind "pin" | "card" · optional
slot integer, at least 1 · optional Absent, the hub picks the lowest free slot; with none free, 409 slots_full.

Responses

201 Created. · returns a Credential

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.
409 slots_full: no slot named and none free on the lock.
422 command_refused The hub refused the command, for example a lock that did not join securely enough to be driven.
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.
DELETE /hubs/{hub_id}/devices/{device_id}/users/{user_id}/credentials/{credential_id}

Revoke a credential now

Needs the hubs:write scope.

Parameters

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

Responses

200 Revoked; applied turns true when the lock confirms. · returns a Credential

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.
422 command_refused The hub refused the command, for example a lock that did not join securely enough to be driven.
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.
GET /hubs/{hub_id}/devices/{device_id}/users

A lock's users and their credentials

Needs the hubs:read scope.

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 users. Codes are never returned.

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.
POST /hubs/{hub_id}/devices/{device_id}/users

Add a user, with credentials and a schedule

Needs the hubs:write scope.

The hub writes each credential to the lock while the schedule allows, in the site's time zone, even while offline from the cloud.

Parameters

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

Body

label string, up to 100 characters · required
credentials array of CredentialRequest · optional
enabled boolean, default true · optional
schedule AccessSchedule or null · optional
type "general" | "disposable" | "non_access" · optional

Responses

201 Created. · returns a LockUser

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.
409 slots_full: a credential named no slot and none is free; the user isn't kept.
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.