Password Management APIs

Last Updated on : 2023-06-15 05:15:03

Create passwords

The following figure shows how password creation works for a Zigbee lock.
- The following describes the process flow when the Zigbee lock works fine:
  - The caller calls the API to create a password.
  - The cloud sends a password to the gateway.
  - The gateway sends the password to the lock.
  - The lock responds to the gateway: Password settings succeeded.
  - The gateway reports the password status: Password settings succeeded.
  - The cloud updates password status: Password settings succeeded.
  - The caller polls the password status until it gets the status of success or failure. The polling times out after 25 seconds.
- The following describes the process flow when an exception occurs in the Zigbee lock.
  - The caller calls the API to get the lock information.
  - The caller calls the API to create a password that is encrypted with the local key.
  - The cloud sends a password to the gateway.
  - The gateway sends the password to the lock.
  - The lock does not respond.
  - The gateway resends the password three times.
  - The gateway reports the password status: Password settings failed.
  - The cloud updates the password status: Password settings failed.
  - The caller polls the password status until it gets the status of success or failure. The polling times out after 25 seconds.

Encrypt passwords

Password Management APIs

Smart lock APIs

Get a temporary key for password encryption

Applicable lock types

Wi-Fi lock
Zigbee lock
Bluetooth lock
Zigbee lock for hotel use
Wi-Fi lock with video talk

API endpoint

POST /v1.0/devices/{device_id}/door-lock/password-ticket

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/password-ticket

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

Description of result

Parameter	Type	Description
ticket_id	String	The ID of a specified temporary key.
ticket_key	String	The temporary key. It can be used after decryption with AES using the `Access Secret` that is issued by the platform.
expire_time	Long	The remaining validity period.

Sample response on success

{
    "result": {
        "expire_time": 360,
        "ticket_id": "9wxxoLM",
        "ticket_key": "901CC35A67DA3429C38E9622xxxxx3EAE1CE333462356D257FD1D3E5C"
    },
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Create a temporary password

Applicable lock types

Wi-Fi lock
Zigbee lock
Bluetooth lock
Zigbee lock for hotel use
Keepalive lock
Wi-Fi lock with video talk
Wi-Fi access control devices
Bluetooth fittings

API endpoint

POST /v1.0/devices/{device_id}/door-lock/temp-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
Name	String	BODY	The name of a specified temporary password.	Yes
password	String	BODY	The length of the original password is seven digits for Wi-Fi locks and six digits for Zigbee locks and Bluetooth locks. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key `ticket_key` with AES using the `Access Secret` that is issued by the platform. The output format is hex.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds (s).	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds (s).	Yes
password_type	String	BODY	The password is encrypted using a `ticket`.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	Indicates the number of times a password can be used. Valid values: `1`: A password can only be used once before it expires. `0`: A password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the periodic password feature.	No
relate_dev_list	array	BODY	The list of linked devices. The length is one digit. Only Bluetooth lock accessories are supported.	No
schedule_list	List	BODY	The parameter list of the periodic password feature.	No

Description of schedule_list

Parameter	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day, in minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day, in minutes.	Yes
working_day	Int	BODY	The day of the week. Each value accumulates. Valid values: `1`: Sunday `2`: Monday `4`: Tuesday `8`: Wednesday `16`: Thursday `32`: Friday `64`: Saturday	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/temp-password

{
    "password": "956FAD7xxxxxx09C68E168B77",
    "password_type": "ticket",
    "ticket_id": "xxxxxx",
    "effective_time": 1579156726,
    "invalid_time": 1579243126,
    "name":"test",
    "phone": 11233213,
    "time_zone":"",
    "schedule_list":[{
        "effective_time": 720,
        "invalid_time": 1080,
        "working_day":  0
    }],
    "relate_dev_list":["vdevo153459****"]
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

Description of result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 124367346
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Create an unnamed temporary password

Applicable lock types

Wi-Fi lock
Zigbee lock
Bluetooth lock
Zigbee lock for hotel use
Wi-Fi lock with video talk
Bluetooth fittings

API endpoint

POST /v2.0/devices/{device_id}/door-lock/temp-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password	String	BODY	The length of the original password is seven for Wi-Fi locks and six for Zigbee locks and Bluetooth locks. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key `ticket_key` with AES using the `Access Secret` that is issued by the platform.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds (s).	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds (s).	Yes
password_type	String	BODY	The password is encrypted using a `ticket`.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	Indicates the number of times a password can be used. Valid values: `1`: A password can only be used once before it expires. `0`: A password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the periodic password feature.	No
relate_dev_list	array	BODY	The list of linked devices. The length is one digit. Only Bluetooth lock accessories are supported.	No
schedule_list	List	BODY	The parameter list of the periodic password feature.	No

Description of schedule_list

Parameter	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day, in minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day, in minutes.	Yes
working_day	Int	BODY	The day of the week. Each value accumulates. Valid values: `1`: Sunday `2`: Monday `4`: Tuesday `8`: Wednesday `16`: Thursday `32`: Friday `64`: Saturday	Yes

Sample request

POST /v2.0/devices/vdevo153459260090544/door-lock/temp-password

{
    "password": "956FAD7xxxxxx09C68E168B77",
    "password_type": "ticket",
    "ticket_id": "xxxxxx",
    "effective_time": 1579156726,
    "invalid_time": 1579243126,
    "phone": 11233213,
    "time_zone":"",
    "schedule_list":[{
        "effective_time": 720,
        "invalid_time": 1080,
        "working_day":  0
    }],
    "relate_dev_list":["vdevo153459****"]
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

Description of result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 124367346
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Synchronize passwords

Applicable lock types

Zigbee lock

After a password is created for a Zigbee lock, if the password status is in configuring, you can call this API to synchronize the password in configuring to the lock. For a single device, this API can only be called once within 60 seconds.

API endpoint

POST /v1.0/devices/{device_id}/door-lock/issue-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	BODY	The password ID. If this field is left blank, all the passwords currently in configuring will be sent to the lock.	No

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/issue-password

{
   "password_id":""
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a temporary password

The periodic password feature is only supported by Zigbee residential lock pro and hotel lock, but is unavailable to other categories currently.

Applicable lock types

Wi-Fi lock
Zigbee lock
Bluetooth lock
Zigbee lock for hotel use

API endpoint

GET /v1.0/devices/{device_id}/door-lock/temp-password/{password_id}

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	URI	The password ID.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/temp-password/xxxx

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

Description of result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.
Name	String	The name of a specified temporary password.
phase	Integer	The status of a specified temporary password.
effective_time	Long	The 10-digit timestamp of the effective time.
invalid_time	Long	The 10-digit timestamp when a temporary password expires.
phone	String	The mobile phone number.
time_zone	String	The time zone.
delivery_status	Integer	The operation status. Valid values: `1`: The password is being configured. `2`: Password configuration succeeds. `3`: Password configuration fails. `4`: The password already exists. `5`: The number of passwords exceeds the limit allowed. `6`: The validity period overlaps with that of another password. Note that this result is only available for Zigbee locks.
schedule_list	List	The parameter list of the periodic password feature.

Description of schedule_list

Parameter	Type	Description
effective_time	Long	The time when a password becomes effective on that day, in minutes.
invalid_time	Long	The time when a password expires on that day, in minutes.
working_day	Int	The day of the week. Each value accumulates. Valid values: `1`: Sunday `2`: Monday `4`: Tuesday `8`: Wednesday `16`: Thursday `32`: Friday `64`: Saturday

Description of phase

Zigbee lock:
- 1: To be created
- 2: Normal
- 3: Frozen
- 4: Deleted
- 5: Creation failed
Wi-Fi lock:
- 0: Deleted
- 1: To be sent
- 2: Sent
- 3: To be deleted
Bluetooth lock:
- 0: Deleted
- 1: To be sent
- 2: Sent
- 3: To be deleted
- 7: Failed to send

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 1001, // The primary key of a temporary password.
        "effective_time": 1530841779, // The 10-digit timestamp of the effective time.
        "invalid_time": 1530881779, // The 10-digit timestamp of the expiration time.
        "name": "Tenant A's password", // The name of a temporary password.
        "phase": 1, // The password status.
        "phone": "123547127362",
        "time_zone":"Asia/Shanghai",
        "delivery_status": 1
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a list of temporary passwords

Applicable lock types

Wi-Fi lock
Zigbee lock
Zigbee lock for hotel use
Bluetooth lock
Wi-Fi lock with video talk
Bluetooth fittings

API endpoint

GET /v1.0/devices/{device_id}/door-lock/temp-passwords

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
valid	Boolean	URL	Specifies whether a password is valid.	No

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords?valid=true

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Description of result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.
Name	String	The name of a specified temporary password.
phase	Integer	The status of a specified temporary password.
effective_time	Long	The 10-digit timestamp of the effective time.
invalid_time	Long	The 10-digit timestamp when a temporary password expires.
phone	String	The mobile phone number.
time_zone	String	The time zone.
delivery_status	Integer	The operation status. Valid values: `1`: The password is being configured. `2`: Password configuration succeeds. `3`: Password configuration fails. `4`: The password already exists. `5`: The number of passwords exceeds the limit allowed. `6`: The validity period overlaps with that of another password. Note that this result is only available for Zigbee locks.
schedule_list	List	The parameter list of the periodic password feature.

Description of schedule_list

Parameter	Type	Description
effective_time	Long	The time when a password becomes effective on that day, in minutes.
invalid_time	Long	The time when a password expires on that day, in minutes.
working_day	Int	The day of the week. Each value accumulates. Valid values: `1`: Sunday `2`: Monday `4`: Tuesday `8`: Wednesday `16`: Thursday `32`: Friday `64`: Saturday

Description of phase

Zigbee lock:
- 1: To be created
- 2: Normal
- 3: Frozen
- 4: Deleted
- 5: Creation failed
Wi-Fi lock:
- 0: Deleted
- 1: To be sent
- 2: Sent
- 3: To be deleted
Bluetooth lock:
- 0: Deleted
- 1: To be sent
- 2: Sent
- 3: To be deleted
- 7: Failed to send

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": [
        {
            "password_id": 1001, // The primary key of a temporary password.
            "effective_time": 1530841779, // The 10-digit timestamp of the effective time.
            "invalid_time": 1530881779, // The 10-digit timestamp of the expiration time.
            "name": "Tenant A's password", // The name of a temporary password.
            "phase": 1, // The password status.
            "phone": "123547127362",
            "time_zone":"Asia/Shanghai",
            "delivery_status": 1
        }
    ]
}

Get a list of temporary passwords of keepalive locks

Applicable lock types

Keepalive Wi-Fi locks
Wi-Fi access control devices

API endpoint

GET /v1.0/smart-lock/devices/{device_id}/stand-by-lock-temp-passwords

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
valid	Boolean	URL	Specifies whether a password is valid.	No
lastRowKey	String	URL	The last row key when you query the records on pages. The value is from the `last_row_key` of the returned result, and it is empty when no value is returned.	No
pageSize	int	URL	The number of records returned on each page.	No

Sample request

GET /v1.0/smart-lock/devices/vdevo12454656****/stand-by-lock-temp-passwords?valid=true&last_row_key=&page_size=10

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Description of result

Parameter	Type	Description
password_id	Long	The ID of a specified temporary password.
Name	String	The name of a specified temporary password.
gmt_create	Long	The 10-digit timestamp when a temporary password is created. Unit: seconds.
effective_time	Long	The 10-digit timestamp of the effective time.
expired_time	Long	The 10-digit timestamp when a temporary password expires.
operate	String	The operation type. Valid values: `ADD`: Add a password. `MODIFY`: Modify a password. `DELETE`: Delete a password.
delivery_status	String	The delivery status. Valid values: `ONGOING`: The password is being sent. `SUCCESS`: The password is successfully sent. `FAILED`: Failed to send the password.
effective_flag	int	The effective status. Valid values: `0`: The password is ineffective. `1`: The password is taking effect. `2`: The password will take effect at the specified time.
schedule_details	List	The parameter list of the periodic password feature.

Description of schedule_list

Parameter	Type	Description
start_minute	int	The time when a password becomes effective on that day, in minutes. Maximum value: `1440`.
end_minute	int	The time when a password expires on that day, in minutes. Maximum value: `1440`.
working_day	Int	The day of the week. Each value accumulates. Valid values: `1`: Sunday `2`: Monday `4`: Tuesday `8`: Wednesday `16`: Thursday `32`: Friday `64`: Saturday
time_zone_id	String	The time zone.

Sample response on success

{
  "has_more": false,
  "last_row_key": "ABCDEFG",
  "records": [
    {
      "delivery_status": "SUCCESS",
      "effective_flag": 1,
      "effective_time": 1628006400,
      "expired_time": 1628265540,
      "gmt_create": 1628088594,
      "name": "369369",
      "operate": "CREATE",
      "password_id": 3351004,
      "phone": "",
      "pwd_type_code": "temp",
      "schedule_details": [
        {
          "all_day": false,
          "start_minute": 0,
          "end_minute": 2359,
          "working_day": 101
        }
      ],
      "sn": 0
    }
  ]
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "System exception. Contact the administrator."
}

Modify a temporary password

Applicable lock types

All-in-one Wi-Fi lock
All-in-one Zigbee lock
Bluetooth lock (password change is not supported)
Zigbee lock for hotel use
Keepalive Wi-Fi locks
Wi-Fi lock with video talk
Wi-Fi access control devices
Bluetooth fittings

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/modify-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	URI	The password ID.	Yes
password	String	BODY	The length of the original password is seven for Wi-Fi locks and six for Zigbee locks. Bluetooth locks do not support password change. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key `ticket_key` with AES using the `Access Secret` that is issued by the platform.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds (s).	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds (s).	Yes
password_type	String	BODY	The password is encrypted using a `ticket`.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	Indicates the number of times a password can be used. Valid values: `1`: A password can only be used once before it expires. `0`: A password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the periodic password feature.	No
schedule_list	List	BODY	The parameter list of the periodic password feature.	No

Description of schedule_list

Parameter	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day, in minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day, in minutes.	Yes
working_day	Int	BODY	The day of the week. Each value accumulates. Valid values: `1`: Sunday `2`: Monday `4`: Tuesday `8`: Wednesday `16`: Thursday `32`: Friday `64`: Saturday	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/{password_id}/modify-password

{
   "phone":"",
   "effective_time":"",
   "invalid_time":"",
   "password":"",
   "password_type":"ticket",
   "ticket_id":"xxx"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Freeze a temporary password

Applicable lock types

Zigbee lock

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/freeze-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	String	URI	The password ID.	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/xxx/freeze-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unfreeze a temporary password

Applicable lock types

Zigbee lock

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/unfreeze-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	String	URI	The password ID.	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/xxx/unfreeze-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Delete a temporary password

Applicable lock types

All-in-one Wi-Fi lock
All-in-one Zigbee lock
Zigbee lock for hotel use
Bluetooth lock
Keepalive Wi-Fi locks
Wi-Fi lock with video talk
Wi-Fi access control devices
Bluetooth fittings

API endpoint

DELETE /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}

Request parameter

Parameter	Type	Parameter type	Description	Yes
device_id	String	URI	The device ID.	Yes
password_id	String	URI	The password ID.	Yes

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a dynamic password

Applicable lock types

Wi-Fi lock
Zigbee lock
Bluetooth lock
Bluetooth fittings

API endpoint

GET /v1.0/devices/{device_id}/door-lock/dynamic-password

Request parameter

Parameter	Type	Parameter type	Description	Yes
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/dynamic-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified dynamic password.

Description of result

Parameter	Type	Description
dynamic_password	String	A dynamic password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "dynamic_password": ""
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get an offline temporary password

Applicable lock types

All-in-one Wi-Fi lock
Bluetooth lock
Bluetooth fittings

API endpoint

POST /v1.0/devices/{device_id}/door-lock/offline-temp-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time.	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time.	Yes
Name	String	BODY	The name of an offline temporary password.	No
type	Int	BODY	The type of password. Valid values: `0`: a password that can be used as many times as needed before it expires. `1`: a one-time password. `9`: a clearing code that clears all passwords. Return a one-time password.	Yes
lang	String	BODY	The language. Set the value to `zh` for the service deployed in mainland China and set the value to `en` for the service deployed outside mainland China.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/offline-temp-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified dynamic password.

Description of result

Parameter	Type	Description
offline_temp_password	String	An offline temporary password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "offline_temp_password": ""
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get an offline temporary password v1.1

Compared with v1.0, support for obtaining and clearing a single offline password is added.

Applicable lock types

All-in-one Wi-Fi lock
All-in-one Zigbee lock
All-in-one Bluetooth lock
Keepalive Wi-Fi locks
Wi-Fi access control devices

API endpoint

POST: /v1.1/devices/{device_id}/door-lock/offline-temp-password

Request parameter

Parameter	Type	Parameter type	Required	Description
device_id	String	uri	true	The device ID.
offline_pwd_add_request	OfflinePwdAddRequest	body	true	The information about an offline password.

Description of offline_pwd_add_request

Parameter	Type	Required	Description
effective_time	Long	false	The time when a password takes effect. Unit: seconds. `1`: Required in case of MULTIPLE(0). `2`: `ONCE(1)/CLEAR_ALL(9)`. Take the hour value of the current time. For example, the current time is `2021-01-23 22:11:12`, so the value of this field is `2021-01-23 22:00:00`. `3`: MULTIPLE(0)/CLEAR_ONE(8). Take the hour value of the entered time. For example, the entered time is `2021-01-27 15:11:12`, so the final value of this field is `2021-01-27 15:00:00`.
invalid_time	Long	false	The time when a password expires. Unit: seconds. `1`: Required in case of MULTIPLE(0). `2`: `ONCE(1)`. Take the hour value of the current time plus 6 hours. For example, the current time is `2021-01-23 22:11:12`, so the value of this field is `2021-01-24 04:00:00`. `3`: `CLEAR_ALL(9)`. Take the hour value of the current time plus 24 hours. For example, the current time is `2021-01-23 22:11:12`, so the value of this field is `2021-01-24 22:00:00`. `4`: MULTIPLE(0)/CLEAR_ONE(8). Take the hour value of the time if this field is not empty. For example, if the entered time is `2021-01-27 15:11:12`, the value of this field is `2021-01-27 15:00:00`.
Name	String	false	The password name.
type	String	true	The type of password. `multiple`: an offline password that can be used for multiple times. `once`: an offline password that can be used only once. `clear_one`: clear an offline password. `clear_all`: clear all offline passwords.
password_id	String	false	The password ID. This value is required when the type is `clear_one`.

Sample response

Parameter	Type	Description
result	OfflinePwdAddResponse	The result of generating an offline temporary password.

Description of result

Parameter	Type	Description
offline_temp_password_id	String	The password ID.
offline_temp_password	String	The password content.
offline_temp_password_name	String	The password name.
effective_time	Long	The time when a password takes effect. Unit: seconds.
invalid_time	Long	The time when a password expires. Unit: seconds.

Sample request

POST: /v1.1/devices/6cdb36b2e489885fa57lzm/door-lock/offline-temp-password

Sample response

{
    "result": {
        "effective_time": 1623747600,
        "offline_temp_password_id": "2345011",
        "offline_temp_password": "0282554135",
        "invalid_time": 1623769200,
        "offline_temp_password_name": "name267"
    },
    "t": 1623748396631,
    "success": true
}

Update the name of an offline password

Applicable lock types

All-in-one Bluetooth lock
Keepalive Wi-Fi locks
Wi-Fi access control devices

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/offline-temp-password/{password_id}

Request parameter

Parameter	Type	Parameter type	Required	Description
device_id	String	URI	true	The device ID.
password_id	Long	URI	true	The password ID.
password_name	String	BODY	true	The password name.

Sample request

PUT /v1.1/devices/6cdb36b2e489885fa5****/door-lock/offline-temp-password

{
  "passwordName": "new0ne"
}

Response parameter

Parameter	Type	Description
result	boolean	The operation result.

Sample response on success

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

Set an advanced password

Applicable lock types

Zigbee lock for hotel use

API endpoint

POST /v1.0/devices/{device_id}/door-lock/advanced-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password	String	Body	The length of the original password is six digits. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key `ticket_key` with AES using the `Access Secret` that is issued by the platform.	Yes
password_type	String	BODY	The password is encrypted using a `ticket`.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
advanced_type	String	BODY	The type of advanced password. Valid values: `admin`: administrator password. `emergency`: emergency password.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/advanced-password

{
    "password_type":"ticket",
    "password":"7A8F9B6197xxxx7C1D66",
    "ticket_id":"fJeqZd45",
    "advanced_type":"emergency"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Clear temporary passwords

Applicable lock types

Zigbee lock for hotel use

API endpoint

POST /v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/reset-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Query an advanced password

Applicable lock types

Type	Supported
Applicable lock type	Zigbee lock for hotel use

API endpoint

GET /v1.0/devices/{device_id}/door-lock/advanced-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
advanced_type	String	URL	The type of advanced password. Valid values: `admin`: administrator password. `emergency`: emergency password.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/advanced-password?advanced_type=admin

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The status of an advanced password.

Description of result

Parameter	Type	Description
advanced_type	String	The type of advanced password. Valid values: `admin`: administrator password. `emergency`: emergency password.
phase	Integer	The status of password configuration. Valid values: `1`: The password is being configured. `2`: Password configuration succeeds. `3`: Password configuration fails.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "advanced_type":"admin",
        "phase":2
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Prev DocRemote Unlock API

Next DocUnlock & Alarm Records API