Identity and Access Management

Last Updated on : 2023-06-29 03:32:15download

Identity and Access Management (IAM) is Tuya’s permission management service dedicated for OpenAPI resources to empower your cloud development. This service enables secure and precision management of access to actions and resources in cloud services.

Functional description

IAM supports user access and permission assignment. You can use these features to create IAM users that grant staff or applications access to required permissions. Example:

  • Grant a maintenance technician access to specified devices and allow them to perform actions, such as checking and sending commands to these devices.
  • Grant a facility manager access to actions in a space. For example, create a subspace, add a device, and create linkage scenes.


IAM enables precision control of resources in cloud projects:

  • Easy and convenient access with IAM users
  • Precision permission management based on actions.
  • Precision permission management based on resources.
  • User permission management in bulk based on roles.

How it works

IAM allows you to access and manage IAM permissions through REST APIs. To check the scope of available API capabilities, you can make an API request to GET /v2.0/cloud/iam/policy/action and get a list of actions. You can also refer to the list of actions in this topic.

The following diagram shows how IAM works.

Identity and Access Management


Term Field Description
Authorize authorize The process in which the administrator grants a user required permissions to finish certain work. An authorization takes effect after required policies and resources are associated with the role that is assigned to a user. This way, the user has access to actions on the specified resources. For example, manage and send commands to devices in a cloud project.
Role role An authorization capability that is close to real-life scenarios, for example, a facility manager or a maintenance technician. The accessible service capabilities and resources vary, depending on different roles. You can define different roles and grant respective permissions to the roles. Then, users can be assigned these roles in bulk.
Action action The minimum service capability. For example, create or delete a space, and send commands. For more information about the definitions of actions, see List of actions.
Effect effect Define whether an action can be performed. Valid values:
  • Allow: The action is allowed.
  • Deny: The action is denied.
The rule of Deny takes precedence in all conditions.
Policy policy Define a group of actions to be allowed or denied. The effect of each action must be clarified. allow_action specifies an allowed action and deny_action specifies a denied action. An allowed action can be performed but a denied action cannot. Example:
  • Define a policy that allows users to create a space and view device properties but does not allow them to delete any space. The definition support fuzzy match to add actions in bulk. For example, use an asterisk (*) to match all actions.
  • Use the expression space:* to match all actions related to a space.
  • Use the expression device:get:* to match all actions about querying device information.
Then, bind the policy with target resources to create a permission that restricts access to these resources.
  • space
  • resource
  • *
The object on which an action is performed. Currently, resources available to IAM include:
  • Space resources (space)
  • Device resources (resource)
  • Global resources (*)
You can make an API request to POST:/v2.0/cloud/iam/role/{role_id}/permission to bind a role with a permission and add resources. In this request, pass in a resource ID that matches the resource type. They are matched in the following ways:
  • For a space resource, the resource ID is a space ID specified by space_id.
  • For a device resource, the resource ID is a device ID specified by device_id.
  • For global resources, the resource ID is set to an asterisk (*) to specify all space resources and device resources.
Permission permission The minimum operation unit for permission management. Each permission consists of a policy and resources, and restricts user access to actions and objects. One or more permissions can be granted to one or more roles.
IAM user user An authorized user over a cloud project structure. You can assign user unique identifiers to users in your proprietary system, and authorize each user to access target actions or resources in the project.

The following diagram shows the relationship between the preceding concepts.

Identity and Access Management


IAM is designed to consist of two steps: manage authorization and authenticate access.

Manage authorization

Currently, permission management is available to developers only. Therefore, a developer account must be used to design, manage, and grant permissions.

Make a token API request to get a developer token before permission management APIs are available.

To manage permissions, perform the following steps:

  • Create a role based on real-life scenarios, for example, a facility manager or a maintenance technician.
  • Create a policy that entails actions required by the role.
  • Bind the role with the action policy and resources.
  • Assign the role to the user to be authorized, so the user can have access to the specified actions and resources.

Authenticate access

To control access to user actions and resources, the system authenticates the IAM user who makes a request. In light of this rule, you must get a user token before a user can make a request. Different from the request to get a developer token, a user unique identifier specified by targetUid is required in the request to get a user token. This identifier must be the same as the value of user_id that is used to assign roles to the user. Otherwise, the user will not have any permissions.

Rules of policy authentication

When an IAM user requests access to resources, the system queries information about all permissions granted to the roles of the user, and determines all respective actions and effect settings. This way, the user permissions are authenticated. The following authentication rules are applied:

  1. An IAM user requests access to certain resources.
  2. The system queries all policies that are bound with the request and processes the actions of Deny type. If this type of action is found from the policy, a Deny decision is returned.
  3. Otherwise, the system continues to search for actions of Allow type. If it is found, an Allow decision is returned.
  4. If it is not found, the system returns a Deny decision and terminates the authentication process.
Identity and Access Management


For a single cloud project, IAM has the following limits:

Item Limit
Number of IAM users Not limited
Number of roles that can be created for each project 100
Number of users to which a role can be assigned 200
Number of roles that a user can be assigned 10
Number of custom policies that can be created for each project 100
Number of permissions that can be bound with a role 10
Length of targetUid assigned to an IAM user 1 to 32 alphanumeric characters only

IAM management API

Category API endpoint Description
Policy POST:/v2.0/cloud/iam/policy Create a policy.
Policy PUT:/v2.0/cloud/iam/policy/{policy_id} Modify information about a policy.
Policy DELETE:/v2.0/cloud/iam/policy/{policy_id} Delete a policy.
Policy GET:/v2.0/cloud/iam/policy/list Query a list of policies available to project developers.
Policy GET:/v2.0/cloud/iam/policy/action Query a list of actions available to a policy.
Role POST:/v2.0/cloud/iam/role Create a role.
Role GET:/v2.0/cloud/iam/role/{role_id} Query a role.
Role PUT:/v2.0/cloud/iam/role/{role_id} Modify information about a role.
Role DELETE:/v2.0/cloud/iam/role/{role_id} Delete a role.
Role POST:/v2.0/cloud/iam/role/{role_id}/permission Bind a role with a permission, including the respective resources and policy.
Role DELETE:/v2.0/cloud/iam/role/{role_id}/permission/{permission_id} Unbind a role from a permission, including the respective resources and policy.
Role GET:/v2.0/cloud/iam/role/{role_id}/permission Query a list of permissions bound with a role, including the respective resources and policy.
Role GET:/v2.0/cloud/iam/role/list Query a list of roles assigned to tenantCode in a project.
Authorization POST:/v2.0/cloud/iam/role/{role_id}/user/{user_id} Assign a role to a user.
Authorization DELETE:/v2.0/cloud/iam/role/{role_id}/user/{user_id} Revoke a role from a user.
Authorization GET:/v2.0/cloud/iam/role/user/{user_id} Query a list of roles assigned to a user.

List of actions

The following table lists available actions. For other available actions not mentioned in this table, you can make an API request to GET /v2.0/cloud/iam/policy/action and get a list of all available actions. You can choose to use these actions as needed. For more information about how to make API requests to these actions, see Cloud Services API Reference.

Type Service name API endpoint Action
Space management Create a space. POST:/v2.0/cloud/space/creation space:create
Space management Delete a space. DELETE:/v2.0/cloud/space/{space_id} space:remove
Space management Query a space. GET:/v2.0/cloud/space/{space_id} space:get
Space management Modify information about a space. PUT:/v2.0/cloud/space/{space_id} space:modify
Space management Query a list of child nodes in a space. GET:/v2.0/cloud/space/child space:list:child
Space management Query a list of devices in a space. GET:/v2.0/cloud/space/{space_id}/resource space:list:resource
Space management Determine the relationship between two spaces. GET:/v2.0/cloud/space/relation space:relation
Device control Get properties of a things data models. GET:/v2.0/cloud/thing/{device_id}/shadow/properties device:get:shadow
Device control Modify properties of things data model. POST:/v2.0/cloud/thing/{device_id}/shadow/properties device:modify:shadow
Device control Send property values of a things data model.
POST:/v2.0/cloud/thing/{device_id}/shadow/properties/issue device:issue:shadow
Device control Query desired properties of a device. GET:/v2.0/cloud/thing/{device_id}/shadow/properties/desired device:get:shadowDesired
Device control Set desired properties of a device. POST:/v2.0/cloud/thing/{device_id}/shadow/properties/desired device:set:shadowDesired
Device control Invoke an action. POST:/v2.0/cloud/thing/{device_id}/shadow/actions device:execute:shadow
Device control Query a things data model. GET:/v2.0/cloud/thing/{device_id}/model device:get:model
Device group Add a device group. POST:/v2.0/cloud/thing/group devicegroup:create
Device group Rename a group. PUT:/v2.0/cloud/thing/group/{group_id}/{name} devicegroup:modify
Device group Query information about a group. GET:/v2.0/cloud/thing/group/{group_id} devicegroup:get
Device group Delete a group. DELETE:/v2.0/cloud/thing/group/{group_id} devicegroup:remove
Device group Add devices to a group. PUT:/v2.0/cloud/thing/group/{group_id}/devices devicegroup:add:device
Device group Remove devices from a group. DELETE:/v2.0/cloud/thing/group/{group_id}/devices devicegroup:remove:device
Device group Query a list of groups. GET:/v2.0/cloud/thing/group devicegroup:list
Device group Query supported properties of things data models in a group. GET:/v2.0/cloud/thing/group/{group_id}/properties devicegroup:get:property
Device group Set properties of things data models in a group. POST:/v2.0/cloud/thing/group/properties devicegroup:modify:property
Device group Query a list of devices in a group. GET:/v2.0/cloud/thing/group/{group_id}/devices devicegroup:list:device
Device group Query the group to which a device belongs. GET:/v2.0/cloud/thing/group/device/{device_id} device:get:deviceGroup
Device management Query device details. GET:/v2.0/cloud/thing/{device_id} device:get
Device management Query devices in bulk. GET:/v2.0/cloud/thing/batch device:list
Device management Modify basic properties of a device. POST:/v2.0/cloud/thing/{device_id}/attribute device:modify:deviceAttribute
Device management Remove a device. DELETE:/v2.0/cloud/thing/{device_id} device:remove
Device management Restore factory defaults. POST:/v2.0/cloud/thing/{device_id}/reset device:reset
Device management Freeze or unfreeze a device. POST:/v2.0/cloud/thing/{device_id}/freeze device:freeze
Device management Transfer a device. POST:/v2.0/cloud/thing/{device_id}/transfer device:transfer
Device management Get freezing status of a device. GET:/v2.0/cloud/thing/{device_id}/state device:get:state
Device management Query logs of a device. GET:/v2.0/cloud/thing/{device_id}/logs device:get:log
Device management Get logs of reported device properties. GET:/v2.0/cloud/thing/{device_id}/report-logs device:get:reportLog
Device management Run over-the-air (OTA) updates. POST:/v2.0/cloud/thing/{device_id}/firmware/{channel} device:execute:ota
Device management Query the progress of an OTA update. GET:/v2.0/cloud/thing/{device_id}/firmware/{channel}/progress device:get:otaProgress
Device management Check for updates. GET:/v2.0/cloud/thing/{device_id}/firmware device:check:otaFirmware
Scene linkage Add a scene linkage rule. POST:/v2.0/cloud/scene/rule scene:create:rule
Scene linkage Modify a scene linkage rule. PUT:/v2.0/cloud/scene/rule/{rule_id} scene:modify:rule
Scene linkage Delete a scene linkage rule. DELETE:/v2.0/cloud/scene/rule scene:remove:rule
Scene linkage Query a single scene linkage rule. GET:/v2.0/cloud/scene/rule/{rule_id} scene:get:rule
Scene linkage Query a list of scene linkage rules. GET:/v2.0/cloud/scene/rule scene:list:rule
Scene linkage Enable or disable a scene linkage rule. PUT:/v2.0/cloud/scene/rule/state scene:modify:ruleState
Scene linkage Trigger a scene linkage rule. POST:/v2.0/cloud/scene/rule/{rule_id}/actions/trigger scene:execute:rule
Scheduled tasks Add a scheduled task of a device. POST:/v2.0/cloud/timer/device/{device_id} device:create:timer
Scheduled tasks Modify a scheduled task of a device. PUT:/v2.0/cloud/timer/device/{device_id} device:modify:timer
Scheduled tasks Enable or disable a scheduled task. PUT:/v2.0/cloud/timer/device/{device_id}/state device:modify:timerState
Scheduled tasks Delete all scheduled tasks of a device. DELETE:/v2.0/cloud/timer/device/{device_id} device:removeAll:timer
Scheduled tasks Query all scheduled tasks of a device. GET:/v2.0/cloud/timer/device/{device_id} device:list:timer
Scheduled tasks Delete scheduled tasks in bulk. DELETE:/v2.0/cloud/timer/device/{device_id}/batch device:batchRemove:timer

Best practice

For more information, see IAM Practice.