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,
}