Locks

Get Lock Dynamic PIN

Changed on

Creates a temporary guest PIN for a smart lock.

PINs work differently on each lock, and each lock needs different inputs:

LockSeriesSendPINUsable for
Cypheo EliteG1device_id only10 digitsabout 15 minutes
Azhero Smart Door Lock / SL1smart_lock_blackdevice_id, start_time, end_time6 digitsthe time window you asked for

How the PIN works on each lock

For G1 Cypheo Elite, the PIN comes from the clock. It is based on the minute it was created. The lock works out the same PIN from its own clock and checks that they match. Nothing is sent to the lock or stored, so the lock does not need to be online. The PIN works for about 15 minutes and you cannot choose the time window. start_time and end_time are not needed and are ignored if sent.

For the Azhero Smart Door Lock / SL1, the PIN is stored on the lock for the time window you choose, so you must send start_time and end_time. If a guest PIN already on the lock covers your time window, that PIN is returned and no new one is created.

Request

WhereNameRequiredValue
Headerx-api-keyYesYour developer API key.
HeaderAuthorizationYesBearer <access_token>
HeaderContent-TypeYesapplication/json
Bodydevice_idYesA lock on your account.
Bodystart_timeOnly for Azhero / SL1When the PIN starts working. UTC epoch seconds. Ignored by G1.
Bodyend_timeOnly for Azhero / SL1When the PIN stops working. UTC epoch seconds, later than start_time. Ignored by G1.

If the device_id is not a lock, you get a 400 error that says what kind of device it is.

Both time fields are epoch seconds, not milliseconds. If you send milliseconds, the time window will be far too long.

Response

{
  "status": "Success",
  "message": {
    "data": {
      "otp": "482913",
      "validStartTime": 1767304800,
      "validEndTime": 1767305039
    }
  }
}
FieldTypeMeaning
message.data.otpstringThe PIN to give your guest. It is a string, not a number, because it can start with 0.
message.data.validStartTimeintegerWhen it starts working, epoch seconds.
message.data.validEndTimeintegerWhen it stops working, epoch seconds.

Always use the time window from the response. For G1, the time window is short and set by the lock. For Azhero / SL1, it can be wider than you asked for, because an existing guest PIN that covers your time window is reused.

A PIN cannot be cancelled before it expires, so ask for short time windows.

When an Azhero Smart Door Lock / SL1 creates a new PIN, the API returns the reply from the lock's own platform without changing it. Its format can differ from the example above.

post/get_lock_dynamic_pin

Request

  • Base URL
    https://api.developer.atomberg-iot.com/v2
  • Auth
    API key in header x-api-key and HTTP bearer

Request body

device_idstring required

A lock on your account, from 'Get List of Devices'.

start_timeinteger

Required only for the Azhero Smart Door Lock / SL1 (series smart_lock_black). When the PIN starts working, in UTC epoch seconds. Ignored by G1.

end_timeinteger

Required only for the Azhero Smart Door Lock / SL1 (series smart_lock_black). When the PIN stops working, in UTC epoch seconds, later than start_time. Ignored by G1.

Example request

{
  "device_id": "aabbccddee01",
  "start_time": 1767304800,
  "end_time": 1767330000
}

Response

OK

statusstring

Success on a 2xx, Error otherwise.

Example response

{
  "status": "Success",
  "message": {
    "data": {
      "otp": "482913"
    }
  }
}

Changes