Temporary Password SDK

Last Updated on : 2024-10-11 02:16:04download

The @ray-js/wechat-ms-password SDK integrates capabilities that enable users to generate temporary passwords for a device, including dynamic passwords, one-time passwords, time-limited passwords, custom passwords, and clearing codes.

Password types

Password type Internet connection
required
Activation method How to delete a password
before it expires
Custom password Yes A custom password is activated once it is created. Connect the lock to the app, and delete the password through the app.
Time-limited password No Use the password at least once within the 24 hours after it takes effect. A time-limited password can be used multiple times within its validity period. Delete the password using a clearing code.
One-time password No The password takes effect once it is created. A one-time password can be used only once within the 6 hours after it is created. Use it once.
Dynamic password No The password takes effect once it is created. A dynamic password can be directly used within the 5 to 10 minutes after it is created. Wait for the password to automatically become invalid.
Clearing code No Use the password once within the 24 hours after it is created. Use it once.

Installation

yarn add @ray-js/wechat-ms-password

// or

npm install @ray-js/wechat-ms-password

Create a temporary password

createPassword

Request parameters

Parameter Type Description Required
device_id string The device ID. true
pwd_type_code string The password type. Valid values:
  • dynamic: dynamic password
  • temp: custom password
  • once: one-time password
  • multiple: time-limited password
  • clear_all: code for clearing all existing time-limited passwords
  • clear_one: code for clearing one existing time-limited password
true
name string The password name. It is empty by default. false
password_id string The password ID. It is empty by default. If pwd_type_code is set to clear_one, this parameter is required. false
effective_time number The effective time. The default value is the current time. Unit: ms. false
invalid_time number The expiration time. The default value is the next hour from the current time. Unit: ms. false

Response parameters

Parameter Type Description
dynamic_password string The dynamic password.
temp_password string The custom password.
effective_time number The effective time.
invalid_time number The expiration time.
offline_temp_password string The generated password.
offline_temp_password_id string The password ID.
offline_temp_password_name number The password name.

Sample request

import MsPasswordApi from '@ray-js/wechat-ms-password';

MsPasswordApi.createPassword({
  device_id: 'vdevo172164201350692',
  effective_time: 1722397508,
  invalid_time: 1722401108,
  name: '',
  pwd_type_code: 'once',
})
  .then(response => {
    console.log(response);
  })
  .catch(error => console.log(error));

Sample response

{
  effective_time: 1722394800,
  invalid_time: 1722416400,
  offline_temp_password: '4266733256',
  offline_temp_password_id: '697404212',
  offline_temp_password_name: 'one-time password',
}

Save a temporary password

savePassword

Request parameters

Parameter Type Description Required
device_id string The device ID. true
pwd_type_code string The password type. Valid values:
  • temp: custom password
  • once: one-time password
  • multiple: time-limited password
  • clear_all: code for clearing all existing time-limited passwords
  • clear_one: code for clearing one existing time-limited password
true
password_id number The password ID. If pwd_type_code is not set to temp, this parameter is used. true
password_name string The password name. If pwd_type_code is not set to temp, this parameter is used. true
password string The password. If pwd_type_code is set to temp, this parameter is used. true
effective_time number The effective time. Unit: s. For example, new Date()÷1000. If pwd_type_code is set to temp, this parameter is used. true
invalid_time number The expiration time. If pwd_type_code is set to temp, this parameter is used. true
name string The password name. If pwd_type_code is set to temp, this parameter is used. false

Response parameters

bool | string: Indicates whether the password is saved. | The password ID.

Sample request

import MsPasswordApi from '@ray-js/wechat-ms-password';

MsPasswordApi.savePassword({
  device_id: 'vdevo172164201350692',
  password_id: 699103212,
  password_name: 'password',
  pwd_type_code: 'temp',
})
  .then(response => {
    console.log(response);
  })
  .catch(error => console.log(error));

Sample response

true;

Get the list of temporary passwords

getTempPwdList

Request parameters

Parameter Type Description Required
device_id string The device ID. true
page_size number The number of passwords per page. The default value is 200. false
pwd_type_codes string The password type. Valid values:
  • temp: custom password
  • once: one-time password
  • multiple: time-limited password
  • clear_all: code for clearing all existing time-limited passwords
  • clear_one: code for clearing one existing time-limited password
false
query_id string The query ID of a password. The default value is "". When pull-to-refresh is needed because there are too many passwords (has_more is true), query_id is the query ID of the 100th password. false

Response parameters

Parameter Type Description
has_more bool Indicates whether the next page exists.
records recordItem[] The password records.

Description of recordItem

Parameter Type Description
auth_result number The authorization result.
delivery_status string The progress status. Valid values:
  • ONGOING: synchronizing
  • SUCCESS: succeeded
  • FAILED: failed
effective_flag number Indicates whether the password is valid. Valid values:
  • 0: invalid
  • 1: valid
  • 2: to be valid later
effective_time number The effective time.
expired_time number The expiration time.
gmt_create number The creation time.
name string The name.
operate string The operation type.
password_id string The password ID.
phone string The phone number.
pwd_type_code string The password type. Valid values:
  • temp: custom password
  • once: one-time password
  • multiple: time-limited password
  • clear_all: code for clearing all existing time-limited passwords
  • clear_one: code for clearing one existing time-limited password
query_id number The query ID.
sn number The serial number (SN).
has_clear_pwd bool Indicates whether a clearing code exists. The value of this field may be true only when pwdTypeCode is multiple.
revoked_pwd_name string The name of the cleared password. This field has a value only when pwdTypeCode is clear_one.
revoked_pwd_effective_time string The effective time of the cleared password. This field has a value only when pwdTypeCode is clear_one.
revoked_pwd_invalid_time string The expiration time of the cleared password. This field has a value only when pwdTypeCode is clear_one.

Sample request

import MsPasswordApi from '@ray-js/wechat-ms-password';

MsPasswordApi.getTempPwdList({
  device_id: 'vdevo172164201350692',
  page_size: 200,
  pwd_type_codes: 'multiple,once,clear_all,clear_one,temp',
  query_id: '',
  session_id: '1722411999842',
  target_status: '',
})
  .then(response => {
    console.log(response);
  })
  .catch(error => console.log(error));

Sample response

{
  records: [
    {
      effective_flag: 1,
      effective_time: 1722409200000,
      expired_time: 1722430800000,
      gmt_create: 1722411994000,
      has_clear_pwd: false,
      name: "one-time password",
      password_id: 697404512,
      phone: "",
      pwd_type_code: "once",
      query_id: 3652502812,
      revoked_pwd_name: "",
    },
     {
      effective_flag: 1,
      effective_time: 1722409200000,
      expired_time: 1722495600000,
      gmt_create: 1722411895000,
      has_clear_pwd: false,
      name: "clearing code",
      password_id: 697404412,
      phone: "",
      pwd_type_code: "clear_all",
      query_id: 3652502812,
      revoked_pwd_name: "",
    }
  ],
  has_more: false,
}

Update the name of a valid temporary password

updatePasswordName

Request parameters

Parameter Type Description Required
device_id string The device ID. true
password_id number The password ID. true
password_name string The password name. true
pwd_type_code string The password type. Valid values:
  • temp: custom password
  • once: one-time password
  • multiple: time-limited password
  • clear_all: code for clearing all existing time-limited passwords
  • clear_one: code for clearing one existing time-limited password
true

Response parameters

Return a boolean value to indicate whether the name of the valid temporary password is updated.

Sample request

import MsPasswordApi from '@ray-js/wechat-ms-password';

MsPasswordApi.updatePasswordName({
  device_id: 'vdevo172164201350692',
  password_id: 699103212,
  password_name: 'password',
  pwd_type_code: 'temp',
})
  .then(response => {
    console.log(response);
  })
  .catch(error => console.log(error));

Sample response

true;

Delete a temporary password

deletePassword

Only the following types of passwords can be deleted: custom passwords (whose pwd_type_code is temp) and invalid non-custom passwords (whose pwd_type_code is not temp).

Request parameters

Parameter Type Description Required
device_id string The device ID. true
password_id number The password ID. true
effective_flag number Indicates whether the password is valid. Valid values:
  • 0: invalid
  • 1: valid
  • 2: to be valid later
true
pwd_type_code string The password type. Valid values:
  • temp: custom password
  • once: one-time password
  • multiple: time-limited password
  • clear_all: code for clearing all existing time-limited passwords
  • clear_one: code for clearing one existing time-limited password
true

Response parameters

Return a boolean value to indicate whether the password is deleted.

Sample request

import MsPasswordApi from '@ray-js/wechat-ms-password';

MsPasswordApi.deletePassword({
  device_id: 'vdevo172164201350692',
  password_id: 699100912,
  effective_flag: 0,
  pwd_type_code: 'once',
})
  .then(response => {
    console.log(response);
  })
  .catch(error => console.log(error));

Sample response

true;

Get the list of valid time-limited passwords

listOfflinePassword

The list of valid time-limited passwords can be gotten only when the clearing code is of the clear_one type.

Request parameters

Parameter Type Description Required
device_id string The device ID. true
page_no number The page number. The default value is 1. false
page_size number The number of records per page. The default value is 200. false

Response parameters

Parameter Type Description
records recordItem[] The time-limited password records.
has_more bool Indicates whether the next page exists.
total number The total number of records.
total_pages bool The total number of pages.

Description of recordItem

Parameter Type Description
auth_result number The authorization result.
delivery_status string The progress status. Valid values:
  • ONGOING: synchronizing
  • SUCCESS: succeeded
  • FAILED: failed
effective_flag number Indicates whether the password is valid. Valid values:
  • 0: invalid
  • 1: valid
  • 2: to be valid later
effective_time number The effective time.
expired_time number The expiration time.
gmt_create number The creation time.
name string The name.
operate string The operation type.
password_id string The password ID.
phone string The phone number.
pwd_type_code string The password type. Valid values:
  • temp: custom password
  • once: one-time password
  • multiple: time-limited password
  • clear_all: code for clearing all existing time-limited passwords
  • clear_one: code for clearing one existing time-limited password
query_id number The query ID.
sn number The SN.
has_clear_pwd bool Indicates whether a clearing code exists. The value of this field may be true only when pwdTypeCode is multiple.
revoked_pwd_name string The name of the cleared password. This field has a value only when pwdTypeCode is clear_one.
revoked_pwd_effective_time string The effective time of the cleared password. This field has a value only when pwdTypeCode is clear_one.
revoked_pwd_invalid_time string The expiration time of the cleared password. This field has a value only when pwdTypeCode is clear_one.

Sample request

import MsPasswordApi from '@ray-js/wechat-ms-password';

MsPasswordApi.listOfflinePassword({
  device_id: 'vdevo172164201350692',
})
  .then(response => {
    console.log(response);
  })
  .catch(error => console.log(error));

Sample response

{
  records: [
    {
      gmt_create: 1722844885,
      gmt_expired: "1722848400",
      gmt_start: "1722844800",
      has_clear_pwd: false,
      opt_uid: "ay1557901851281KP4Ug",
      pwd: "0000960001",
      pwd_id: "699104112",
      pwd_name: "time-limited password",
      pwd_type_code: "multiple",
      revoked_pwd_name: "",
      status: 1,
    }
  ],
  has_more: false,
  total: 1,
  total_pages: 1,
}