Tuya.com
English
简体中文
Register
Developer Platform
English
简体中文
Register
Developer Platform
Cloud Services API Reference
search
Search By Document Directory
Cloud Services API ReferenceAdvanced Device ServicesExtension APIsSmart Lock Open APIsPassword Management APIs

Password Management APIs

Last Updated on : 2025-01-02 09:15:54download

Create passwords

  • The following figure shows how password creation works for a Zigbee lock.

    Password Management APIs

    • 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

Sample code for Java

Download the sample code for Java.

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 Advanced Encryption Standard (AES, aes-256-ecb mode) 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 Unlocking APIs
Next DocUnlocking & Alert History APIs
Language
English
English
简体中文
844-672-5646
7×24 Service Hotline
Marketing Cooperation
marketing@tuya.com
Business Cooperation
vip@tuya.com
Customer Service
service@tuya.com
Media Inquiry
pr@tuya.com
Contact UsTuyaExpoApp MallTuyaGo
Privacy PolicyTerms of UseCalifornia Privacy NoticeBug BountyDo Not Sell or Share My Information
© 2025 Tuya Inc.
English
English
简体中文