Access Control

Last Updated on : 2023-06-05 02:41:22download

Access control supports the following capabilities:

Access control with passwords: The password of an access control device such as a smart lock can be sent to a specific email address. The user of the email address can use this password to unlock the door. Currently, only online passwords can be sent.
Members allowed for access: A specified user can be granted access permissions for a long time. The member allowed for access can only use the target access control device.

Functional description

After login, an object of TuyaResidenceAccess can be declared to call all object methods of this class.

- (TuyaResidenceAccess *)access {
    if (!_access) {
        _access = [[TuyaResidenceAccess alloc] init];
    }
    return _access;
}

Access control of app users

Add an app user allowed for access

API description

- (void)addAppAccessWithModel:(TuyaResidenceAddAppAccessModel *)appAccessModel
                      success:(TYSuccessBOOL)success
                      failure:(TYFailureError)failure;

Parameters

Parameter	Description
TuyaResidenceAddAppAccessModel	The request model to add an app user allowed for access.
success	The success callback.
failure	The failure callback.

Data model of TuyaResidenceInvitationCreateRequestModel

Field	Type	Description
siteId	long long	The current site ID.
account	NSString	The account of the member to be added.
nickname	NSString	The nickname of a specified user.
deviceIdList	NSArray<NSString *>	The list of devices.
startTime	long	The 13-digit start timestamp for the validity period of the authorization. If the value is set to `-1`, the authorization is permanently valid.
endTime	long	The 13-digit end timestamp for the validity period of the authorization. If the value is set to `-1`, the authorization is permanently valid.
userType	TuyaResidenceAccessUserType	The type of member. Valid values: `20`: administrator `30`: common member For access control sites and business-authorized sites, only app users whose `userType` is `30` can be created. The type of site is indicated by `siteType` of `TuyaResidenceSiteModel`.

Example

Objective-C:

[self.access addAppAccessWithModel:reqModel success:^(BOOL result) {

} failure:^(NSError *error) {

}];

Query a list of app users allowed for access

API description

- (void)fetchAppAccessListWithSiteId:(long long)siteId
                           effective:(BOOL)effective
                              pageNo:(NSInteger)pageNo
                            pageSize:(NSInteger)pageSize
                             success:(void(^)(NSArray<TuyaResidenceAppAccessModel *> *userList))success
                             failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
effective	`YES`: The authorization is valid. `NO`: The authorization has expired.
pageNo	The page number, starting from `1` and incremented by `1` for each request.
pageSize	The number of entries to be returned per page. Valid values: `10` to `100`.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchAppAccessListWithSiteId:siteId effective:YES pageNo:1 pageSize:20 success:^(NSArray<TuyaResidenceAppAccessModel *> * _Nonnull userList) {

} failure:^(NSError *error) {

}];

Query details of an app user allowed for access

API description

- (void)fetchAppAccessUserDetailWithSiteId:(long long)siteId
                              accessUserId:(NSString *)accessUserId
                                   success:(void(^)(TuyaResidenceAppAccessDetailModel *userDetail))success
                                   failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchAppAccessUserDetailWithSiteId:siteId accessUserId:accessUserId success:^(TuyaResidenceAppAccessDetailModel * _Nonnull userDetail) {

} failure:^(NSError *error) {

}];

Query access records of app users

API description

- (void)fetchAppAccessPassRecordWithSiteId:(long long)siteId
                              accessUserId:(NSString *)accessUserId
                                    pageNo:(NSInteger)pageNo
                                  pageSize:(NSInteger)pageSize
                                   success:(void(^)(NSArray<TuyaResidenceAccessRecordModel *> *accessUserRecordList))success
                                   failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
accessUserId	The member ID.
pageNo	The page number, starting from `1` and incremented by `1` for each request.
pageSize	The number of entries to be returned per page. Valid values: `10` to `100`.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchAppAccessPassRecordWithSiteId:siteId accessUserId:accessUserId pageNo:1 pageSize:20 success:^(NSArray<TuyaResidenceAccessRecordModel *> * _Nonnull accessUserRecordList) {

} failure:^(NSError *error) {

}];

Query total number of app users allowed for access

API description

- (void)fetchAppAccessTotalWithSiteId:(long long)siteId
                            effective:(BOOL)effective
                              success:(void(^)(NSInteger total))success
                              failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
effective	`YES`: The authorization is valid. `NO`: The authorization has expired.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchAppAccessTotalWithSiteId:siteId effective:effective success:^(NSInteger total) {

} failure:^(NSError *error) {

}];

Add devices to app user

API description

- (void)addAppAccessDeviceWithSiteId:(long long)siteId
                        accessUserId:(NSString *)accessUserId
                        deviceIdList:(NSArray<NSString *> *)deviceIdList
                             success:(TYSuccessHandler)success
                             failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
accessUserId	The member ID.
deviceIdList	The list of target device IDs.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access addAppAccessDeviceWithSiteId:siteId accessUserId:accessUserId deviceIdList:deviceIdList success:^{

} failure:^(NSError *error) {

}];

Remove devices from app user

API description

- (void)removeAppAccessDeviceWithSiteId:(long long)siteId
                           accessUserId:(NSString *)accessUserId
                               deviceId:(NSString *)deviceId
                                success:(TYSuccessHandler)success
                                failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
accessUserId	The member ID.
deviceIdList	The list of target device IDs.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access removeAppAccessDeviceWithSiteId:siteId accessUserId:accessUserId deviceId:deviceId success:^{

} failure:^(NSError *error) {

}];

Remove app user allowed for access

API description

- (void)removeAppAccessWithSiteId:(long long)siteId
                     accessUserId:(NSString *)accessUserId
                          success:(TYSuccessHandler)success
                          failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
accessUserId	The member ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access removeAppAccessWithSiteId:siteId accessUserId:accessUserId success:^{

} failure:^(NSError *error) {

}];

Update app user information

API description

- (void)updateAppAccessWithSiteId:(long long)siteId
                     accessUserId:(NSString *)accessUserId
                         nickName:(NSString *)nickName
                         userType:(TuyaResidenceAccessUserType)userType
                        startTime:(long)startTime
                          endTime:(long)endTime
                          success:(TYSuccessHandler)success
                          failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
accessUserId	The member ID.
nickName	The nickname.
userType	The type of member. Valid values: `20`: administrator `30`: common member For access control sites and business-authorized sites, only app users whose `userType` is `30` can be created.
startTime	The 13-digit start timestamp for the validity period of the authorization. If the value is set to `-1`, the authorization is permanently valid.
endTime	The 13-digit end timestamp for the validity period of the authorization. If the value is set to `-1`, the authorization is permanently valid.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access updateAppAccessWithSiteId:siteId accessUserId:accessUserId nickName:nickname userType:userType startTime:startTime endTime:endTime success:^{

} failure:^(NSError *error) {

}];

Access control with passwords

Add a member allowed for access with a password

API description

- (void)addPasswordAccessWithModel:(TuyaResidenceAddPasswordAccessModel *)requstModel
                           success:(TYSuccessHandler)success
                           failure:(TYFailureError)failure;

Parameters

Parameter	Description
TuyaResidenceAddPasswordAccessModel	The request model to add a member allowed for access with a password.
success	The success callback.
failure	The failure callback.

Data model of TuyaResidenceAddPasswordAccessModel

Field	Type	Description
siteId	long long	The site ID.
deviceIdList	NSArray<NSString *>	The list of access control device IDs.
passwordInfo	TuyaResidencePasswordInfoModel	The information about the password.
userList	NSArray<TuyaResidencePasswordUserModel *>	The model of the member allowed for access with a password.

Data model of TuyaResidencePasswordInfoModel

Field	Type	Description
passwordValue	NSString	The password.

Data model of TuyaResidencePasswordUserModel

Field	Type	Description
nickname	NSString	The nickname.
username	NSString	The account.

Example

Objective-C:

[self.access addPasswordAccessWithModel:reqModel success:^{

} failure:^(NSError *error) {

}];

Query a list of users allowed for access with passwords

API description

- (void)fetchPasswordAccessListWithSiteId:(long long)siteId
                                effective:(BOOL)effective
                                   pageNo:(NSInteger)pageNo
                                 pageSize:(NSInteger)pageSize
                                  success:(void (^)(NSArray<TuyaResidencePasswordAccessModel *> *accessPasswordList))success
                                  failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
effective	`YES`: valid authorization `NO`: expired authorization
pageNo	The page number, starting from `1` and incremented by `1` for each request.
pageSize	The number of entries to be returned per page. Valid values: `10` to `100`.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchPasswordAccessListWithSiteId:siteId effective:YES pageNo:1 pageSize:20 success:^(NSArray<TuyaResidencePasswordAccessModel *> * _Nonnull accessPasswordList) {

 } failure:^(NSError *error) {

}];

Query details of user allowed for access with password

API description

- (void)fetchPasswordAccessUserDetailWithSiteId:(long long)siteId
                                    authGroupId:(NSString *)authGroupId
                                        success:(void (^)(TuyaResidencePasswordAccessModel *accessPasswordModel))success
                                        failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
authGroupId	The authorization group ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchPasswordAccessUserDetailWithSiteId:siteId authGroupId:authGroupId success:^(TuyaResidencePasswordAccessModel * _Nonnull accessPasswordModel) {

} failure:^(NSError *error) {

}];

Query password access records of users

API description

- (void)fetchPasswordAccessPassRecordWithSiteId:(long long)siteId
                                    authGroupId:(NSString *)authGroupId
                                         pageNo:(NSInteger)pageNo
                                       pageSize:(NSInteger)pageSize
                                        success:(void(^)(NSArray<TuyaResidenceAccessRecordModel *> *accessUserRecordList))success
                                        failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
authGroupId	The authorization group ID.
pageNo	The page number, starting from `1` and incremented by `1` for each request.
pageSize	The number of entries to be returned per page. Valid values: `10` to `100`.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchPasswordAccessPassRecordWithSiteId:siteId authGroupId:authGroupId pageNo:1 pageSize:20 success:^(NSArray<TuyaResidenceAccessRecordModel *> * _Nonnull accessUserRecordList) {

} failure:^(NSError *error) {

}];

Query total number of users allowed for access with passwords

API description

- (void)fetchPasswordAccessTotalWithSiteId:(long long)siteId
                                 effective:(BOOL)effective
                                   success:(void(^)(NSInteger total))success
                                   failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
effective	`YES`: valid authorization `NO`: expired authorization
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchPasswordAccessTotalWithSiteId:siteId effective:effective success:^(NSInteger total) {

} failure:^(NSError *error) {

}];

Remove user allowed for access with password

Removes a user allowed for access with a password from a device that must be online to receive the command. Otherwise, the user will fail to be removed. You can call [TuyaSmartDevice deviceWithDeviceId:deviceId] to query device information, including its online status.

API description

- (void)removePasswordAccessWithSiteId:(long long)siteId
                           authGroupId:(NSString *)authGroupId
                               success:(TYSuccessHandler)success
                               failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
authGroupId	The authorization group ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access removePasswordAccessWithSiteId:siteId authGroupId:authGroupId success:^{

} failure:^(NSError *error) {

}];

Add devices to users allowed for access with passwords

Adds devices to users allowed for access with passwords. The device must be online to receive the command. Otherwise, the devices will fail to be added. You can call [TuyaSmartDevice deviceWithDeviceId:deviceId] to query device information, including its online status.

API description

- (void)addPasswordAccessDeviceWithSiteId:(long long)siteId
                              authGroupId:(NSString *)authGroupId
                             deviceIdList:(NSArray<NSString *> *)deviceIdList
                                  success:(TYSuccessHandler)success
                                  failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
authGroupId	The authorization group ID.
deviceIdList	The list of device IDs.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access addPasswordAccessDeviceWithSiteId:siteId authGroupId:authGroupId deviceIdList:deviceIdList success:^{

} failure:^(NSError *error) {

}];

Remove devices from users allowed for access with passwords

Removes devices from users allowed for access with passwords. The devices must be online to receive the command. Otherwise, the devices will fail to be removed. You can call [TuyaSmartDevice deviceWithDeviceId:deviceId] to query device information, including its online status.

API description

- (void)removePasswordAccessDeviceWithSiteId:(long long)siteId
                                 authGroupId:(NSString *)authGroupId
                                    deviceId:(NSString *)deviceId
                                     success:(TYSuccessHandler)success
                                     failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
authGroupId	The authorization group ID.
deviceId	The device ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access removePasswordAccessDeviceWithSiteId:siteId authGroupId:authGroupId deviceId:deviceId success:^{

} failure:^(NSError *error) {

}];

Update password information for authorized users

API description

- (void)updatePasswordAccessValidityWithSiteId:(long long)siteId
                                   authGroupId:(NSString *)authGroupId
                                  doorPassword:(TuyaResidenceBasePasswordInfoModel *)doorPassword
                                  deviceIdList:(NSArray<NSString *> *)deviceIdList
                                       success:(TYSuccessHandler)success
                                       failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
authGroupId	The authorization group ID.
doorPassword	The model of the lock password.
deviceIdList	The list of device IDs.
success	The success callback.
failure	The failure callback.

Data model of TuyaResidenceBasePasswordInfoModel

Field	Type	Description
authType	TuyaResidencePasswordAuthType	The type of password. Valid values: `TuyaResidencePasswordAuthTypeTemporary`: a temporary password `TuyaResidencePasswordAuthTypePeriodic`: a periodic password
authName	NSString	The authorized name.
effectiveTime	long	The 13-digit timestamp when the password becomes effective.
invalidTime	long	The 13-digit timestamp when the password expires.
scheduleRepeat	NSInteger	The type of schedule. Valid values: `0`: one-time `1`: recurring
schedule	TuyaResidencePasswordScheduleModel	When `scheduleRepeat` is set to `1`, this model is required.

Data model of TuyaResidencePasswordScheduleModel

Field	Type	Description
startClock	NSInteger	The start time of a schedule. Example: `9:00` is represented by `9 * 60 + 0 = 540`. `9:10` is represented by `9 * 60 + 10 = 550`.
endClock	NSInteger	The end time of a schedule. Example: `21:00` is represented by `21 * 60 = 1260`.
weekDay	NSInteger	The weekly recurring method represented by a 7-digit binary value. The recurring date is set to `1`. Otherwise, it is set to `0`. Then, the value is converted into a decimal value. For example, a schedule that recurs from Monday to Friday is represented by `1111100` that is converted into the decimal value `124`.

Example

Objective-C:

[self.access updatePasswordAccessValidityWithSiteId:siteId authGroupId:authGroupId doorPassword:doorModel deviceIdList:deviceIdList success:^{

} failure:^(NSError *error) {

}];

Update nickname of user allowed for access with password

API description

- (void)updatePasswordAccessNicknameWithSiteId:(long long)siteId
                                   authGroupId:(NSString *)authGroupId
                                      nickName:(NSString *)nickName
                                       success:(TYSuccessHandler)success
                                       failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
authGroupId	The authorization group ID.
nickName	The nickname.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access updatePasswordAccessNicknameWithSiteId:siteId authGroupId:authGroupId nickName:nickname success:^{

} failure:^(NSError *error) {

}];

Other features

Query a list of access control devices

API description

- (void)fetchDeviceListWithSiteId:(long long)siteId
                          success:(void(^)(NSArray<TuyaSmartDeviceModel *> *devices))success
                          failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The current site ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access fetchDeviceListWithSiteId:model.siteId success:^(NSArray<TuyaSmartDeviceModel *> * _Nonnull devices) {

} failure:^(NSError *error) {

}];

Determine registered account

API description

- (void)checkAccessAccountWithUserAccount:(NSString *)userAccount
                               success:(TYSuccessBOOL)success
                               failure:(TYFailureError)failure;

Parameters

Parameter	Description
userAccount	The user account.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access checkAccessAccountWithUserAccount:username success:^(BOOL result) {

} failure:^(NSError *error) {

}];

Query user identity

Checks whether a user on a site is a member allowed for access, a site member, or an unregistered user.

API description

- (void)checkAccessAuthorizationWithSiteId:(long long)siteId
                               userAccount:(NSString *)userAccount
                                   success:(void(^)(TuyaResidenceAccessMemberType result))success
                                   failure:(TYFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
userAccount	The user account.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.access checkAccessAuthorizationWithSiteId:siteId userAccount:userAccount success:^(TuyaResidenceAccessMemberType result) {

} failure:^(NSError *error) {

}];