Tuya IoT Cloud Development

Overview of cloud development

• All IoT devices connected to Tuya IoT Cloud can be authorized and controlled by the cloud through API calls.

• You can also make API requests to implement the development of internal business logic.

• Device status listening is opened in the form of message queues, so third-party developers can monitor device status and enable the linkage between different devices.

  Note: For device pairing, you must use an app powered by Tuya or built with Tuya’s App SDK.

Connect to the Cloud Development Platform

Cloud development flowchart

Resources of cloud development project

Pricing

For more information, see Documentation Center. The documents on the official website shall prevail.

On the Tuya IoT Platform, you can query the usage of cloud projects:
• Usage statistics：Click Jump
• API statistics：Click Jump
• Message statistics：Click Jump

Cloud development docs

Tuya Documentation Center provides technical documents related to smart products, app development, cloud development, and Tuya’s business, so you can get started quickly and dive deep into the Tuya IoT Platform.

Cloud development documentation center

For more information：Click Jump

Download the HD image.

API list

For more information：Could Service API

Download the HD image.

Cloud development solutions

Solution	Development method	App / App SDK	Cloud APIs
Solution 1	Smart home projects PaaS	OEM App	Smart home APIs	IoT Core + Basic APIs
Solution 2		Smart Life App SDK
Solution 3	Custom development projects SaaS	IoT Device Management App	Industrial General APIs
Solution 4		Industry App SDK

Note: For device pairing and activation, you must use an app powered by Tuya or built with Tuya’s App SDK.

Comparison of cloud development methods

Smart home PaaS integration

Based on the ‘Powered by Tuya’ ecosystem and Tuya’s smart home PaaS solutions, you can connect devices with Tuya’s all-in-one apps, OEM apps, and App SDK-based apps. Combining with the open capabilities of smart homes, you can build a smart home management platform for homes and rooms.

This type of integration applies to either of the following scenarios:
• You are serving end users who perform device pairing and activation by using Tuya-powered apps. You can get device and user data through Tuya’s OpenAPI operations, and develop a big data management platform that is connected to the cloud.
• Your system runs based on a large number of end users. Tuya has the same user system in the smart home PaaS integration solution. Both systems can be directly associated with each other. After pairing and activation, devices belong to a system that integrates with users and homes. This way, you can get device data and implement device control through Tuya’s OpenAPI operations.
• End users need to create diverse smart home scenarios, such as automation tasks or linkage scenarios of multiple devices in Tuya’s ecosystem.
• For more information, see detailed smart home PaaS integration solutions, from which you can choose your desired cloud development solutions.

Custom SaaS development and integration

The general projects apply to various industry scenarios, such as smart campuses, smart apartments, and smart commercial lighting. Based on the ‘Powered by Tuya’ ecosystem and industry asset systems, you can build customized asset structures that meet various business requirements. The easy-to-use pairing tool and various API products help you deliver cost-efficient industry solutions.

This type of integration applies to either of the following scenarios:
• All devices belong to a company and can be managed with an asset structure tree. The devices can be flexibly authorized and assigned to the staff.
• You are running an integrated control system and requires unified management and integrated control of a large number of devices.
• You can use the OpenAPI provided by Tuya to build diversified business scenarios.
• Tuya provides SaaS Development Framework, so you can easily implement frontend and backend development at the same time.

Smart home PaaS integration solution

The smart home PaaS development of the Cloud Development Platform supports the following solution types.

OEM app + cloud development integration solution

1. Features:
   • Based on the Tuya OEM app, the Cloud Development Platform can be connected on demand. Commands can be sent to devices through the Cloud Development Platform.
   • The devices and the app are connected to the Cloud Development Platform at the same time, and all requests of the devices and the app are sent to the Cloud Development Platform.
   • You are the owner of the generated user and device data. You can manage the data based on Tuya APIs, perform operations such as scheduled tasks and scene setting, and get analytics data.
2. Services provided by Tuya:
   • Standard OEM app or custom app development solution.
   • Provide category-based standard instruction sets, which can be used to control different models of devices in the same category on the Tuya AI+IoT Development Platform.
   • Provide standard APIs to manage user and device data, and provide message queues for you to get real-time device data.
3. Advantages:
   • Quickly connect to devices across categories under the Tuya solutions in a cost-effective way.
   • Make full use of all the functionalities of the Tuya AI+IoT Development Platform.
   • Quickly bring products to market.
   • Get the data from the Tuya AI+IoT Development Platform on demand for various analytics and complex scenario development.

Smart Life App SDK + cloud development integration solution

1. Services provided by Tuya:
   • Provide IoT App SDK with a full range of capabilities.
   • Provide APIs to implement features such as user connection, device discovery, and device control.
   • Provide category-based standard instruction sets, which can control devices on the Tuya AI+IoT Development Platform by category or model.
   • Provide a message queue for you to receive real-time data from devices.
2. Features:
   • Develop an app based on Tuya IoT App SDK.
   • You are running an independent account system, and the account system data is stored in your partner’s IoT cloud.
   • Make full use of all the functionalities of Tuya AI+IoT Development Platform.
   • Get data from the Tuya AI+IoT Development Platform on demand to perform various analytics.

Custom SaaS development and integration

IoT Device Management App + cloud development integration solution

1. Services provided by Tuya:
   • Provide all-in-one pairing app with complete capabilities, requiring no pairing tools.
   • Provide APIs to implement features such as asset creation, user creation and authorization, device binding, and device control.
   • Provide category-based standard instruction sets, which can control devices on the Tuya AI+IoT Development Platform by category or model.
   • Provide a message queue for you to receive real-time data from devices.
2. Features:
   • Tuya’s all-in-one IoT Device Management app relieves you from the hassle of pairing tool apps. You can create users and perform device pairing, and the Cloud Development Platform can be connected as needed. Commands can be sent to devices from the Cloud Development Platform.
   • The devices are connected to the Cloud Development Platform, and all requests of the devices are sent to the Cloud Development Platform.
   • You are the owner of the generated device data. You can manage the device data based on Tuya APIs, and get analytics data.

Industry App SDK+ cloud development integration solution

1. Services provided by Tuya:
   • Provide the Industry App SDK, which can be integrated into your independently developed apps.
   • Provide APIs to implement features such as asset creation, user creation and authorization, device binding, and device control.
   • Provide category-based standard instruction sets, which can control devices on the Tuya AI+IoT Development Platform by category or model.
   • Provide a message queue for you to receive real-time data from devices.
2. Features:
   • Develop an app based on Tuya SDK.
   • You are running an independent account system, and the account system data is stored in a private cloud.
   • Make full use of all the functionalities of Tuya AI+IoT Development Platform.
   • Get data from the Tuya AI+IoT Development Platform on demand to perform various analytics.

Cloud project menus

Tuya IoT Platform

1. Log in to the Tuya IoT Platform：https://iot.tuya.com
   
   Go through the following steps to create and configure a cloud project.
   • Create a project: A cloud project is a collection of resources on the Tuya IoT Platform, including devices, APIs, and data assets. Resources distributed to different projects are isolated from each other.
   • Subscribe to and authorize the required cloud services: You can choose the cloud services provided by Tuya based on the scenarios to speed up your development.

2.You must subscribe to a IoT Core Plan before you can create a cloud project and get access to basic API calls and message services in the Tuya IoT Cloud.

• Steps: Click Cloud in the left-side navigation pane to Upgrade IoT Core Plan
  

Create a cloud development project

A cloud project is a collection of resources on the Tuya IoT Platform. Resources distributed to different projects are isolated from each other. To get started, you need to create a cloud project first.
Subscribe to Cloud Development Plan and create a cloud project.

• Steps: Click Cloud in the left-side navigation pane to enter Cloud Management. Click Create Cloud Project.
  

1. On the Create Cloud Project page, set the required parameters and click Create.
   
   • Project Name: the custom name of the project.
   • Description: the custom description of the project.
   • Development Method: For more information about the development method, see Development Method. For more information about available resources for specific projects, see Resource map of the cloud development project.
   • Industry: Select the industry type of your project, facilitating follow-up statistical analytics.
   • Data Center: Enter the server address of the region where you are located.

2. Authorize API products: Besides the default selections, you can add the desired API products. For more information, see My Services.
   

My cloud projects

Click the created cloud project on the My Cloud Projects page to enter the details page.

Overview

1. Examples of cloud project information:
   • Project Name: the name of the project, such as test creation.
   • Description: the description of the project, such as test.
   • Creation Time: the time when the project was created. For example, 2021-11-11 14:27:28.
   • Industry: Smart home
   • Data Center: the data centers to which the Cloud API requests are sent.
   • Access ID/Client ID and Access Secret/Client Secret: cloud project parameters for API requests.
   • Cloud Application IP Allowlist: After the IP address allowlist is enabled, only specific IP addresses can call the API operations of this project.

2. Edit the information:
   You can edit the overview information, except for the development method.
   

Authorization：

The apps under this authorization are only applicable to the custom cloud projects (asset system).

Note: Click App in the left-side navigation pane to create an app of the smart home PaaS system.

Service API：

Shows the service APIs that are authorized to this cloud project. Click Go to Authorize to authorize the subscribed APIs. If you do not subscribe to an API, the page navigates to My Services.

Note：If a prompt appears during API calls, saying that “No permissions. This project is not authorized to call this API”, confirm whether the API service is subscribed and authorized to this cloud project.

Assets：

Shows the asset device system of a custom cloud project. After creating an asset structure, you can authorize Users (the tab on the right of the Assets tab) with the asset node permissions, and view and manage the devices.

Users：

The user system of a custom cloud project is only applicable to the custom cloud projects (asset system).

Devices：

1. You can view the devices under the smart home PaaS projects and the custom cloud development SaaS projects. The device and user data in different data centers are isolated.
   

   Note ：Data transfer across regions has a risk of violation of the data security regulations. If you request Tuya’s cloud services from an IP address outside the data center region, you are at risk of illegally transferring data.

2. On the All Devices page, you can add a virtual device for debugging. The virtual device is added to the asset structure in a custom development project, and to your app or Tuya’s all-in-one app account in a smart home PaaS project.
   

3. On the pages of Link My App and Link Tuya App Account, you can link devices of the smart home PaaS projects
   

My Service

After you subscribe to an API service and grant the current project access to the API service, you can use the authorization key to access the API.

1. On the details page of API services, you can find the overview, pricing, API list, and authorized projects.

2. Service API of a cloud project shows the APIs that can be called by the current cloud project. You can use online debugging tools for debugging.

API Explorer

You can check API calls and troubleshoot issues with API Explorer.

• Entry 1: Cloud > API Explorer.
• Entry 2: Cloud project page > Service API > Debug.

Data Statistics

You can view the total usage of project resources and the number of API requests and messages.
You can refer to Pricing and check the billing.

Device and user management

For more information：Device Linkage
A cloud development project must be granted access to devices before API requests.
• In a smart home PaaS project, you must link the created app or Tuya account with the cloud project.
• For custom development, you must pair and manage the devices at the asset node of the project.

Device system of smart home projects

The device information under a smart home SaaS project is stored under the personal app account. After the devices are activated and paired by using the apps in the Tuya smart home ecosystem, including OEM app, app developed by App SDK, and all-in-one app, and then linked with the cloud development project, you can call the cloud APIs to manage and control the devices.

The platform provides several methods to link devices in a smart home SaaS project.
• Link my app
• Link Tuya app account

Note 1: The linked OEM app or the app built on top of the Tuya SDK must belong to the same IoT account as the cloud project.

Note 2：One app can be linked with two projects at most. To link with a third project, you must unlink the app with one of the two linked projects first.

FAQ：If “Permission deny” is prompted when you make an API call to request Device_id,
Please confirm:

1. Whether the Device_id in the API request is correct.
2. Whether the device is still bound with the app.
3. Whether the pairing app used by the device is connected to the specified cloud project, and whether the all-in-one app has been granted access to the cloud project by QR code scanning.

Device system of custom development projects

A custom project depends on the asset system, and the device belongs to the cloud project asset. Create users in the asset catalog of the cloud project and authorize them to authorized assets.

IoT Device Management app

For more information：Add Device with IoT Device Management App

Use the all-in-one pairing app of custom development, scan the code to link with the specified cloud application, log in with the account granted access to the asset, and perform device pairing operations at the specified asset node.

Query linked devices under the cloud project

In a cloud project, you can query and find a device based on the device ID, and you can be authorized to make the cloud API requests. Currently, you can query the devices of smart home projects and industry projects on the Tuya IoT Platform.

Manage device query

• Path: My Cloud Projects > Devices > All Devices
  View all devices of this cloud development project, including your apps, Tuya app accounts, or other types of assets.

Query devices under assets

On the Assets tab, you can click asset structures to view the devices under each node and click Debug Device to view the device information.

User management

Smart home app users

In a smart home SaaS project, choose Operation > User Management to view the personal app accounts.

Custom development users

Click Cloud in the left-side navigation pane, click the created project to enter the details page, and then click Users to view the users of custom development projects. The users must be authorized with assets. Only after authorized to the asset node, the specified user can log in to the app for device pairing and control.

Note：The user is only authorized with the specified asset node, and cannot be authorized at the parent node to control the device of the sub-node.

API calls

Tuya opens up a variety of APIs covering business scenarios such as device pairing, smart home management, device control, and smart scenes. You can make API requests according to specific rules in the API integration documents to implement applications.

Data center

The Cloud Development Platform provides a separate endpoint in a different region. You can select an endpoint of the region where your device is deployed. This allows you to reduce the response times of API requests.

Region	Endpoint
China Data Center	https://openapi.tuyacn.com
Western America Data Center	https://openapi.tuyaus.com
Eastern America Data Center	https://openapi-ueaz.tuyaus.com
Central Europe Data Center	https://openapi.tuyaeu.com
Western Europe Data Center	https://openapi-weaz.tuyaeu.com
India Data Center	https://openapi.tuyain.com

API request header

For more information：Request Structure

Parameter	Type	Location	Required	Description
client_id	String	header	Yes	The user ID.
sign	String	header	Yes	The signature that is generated by a specified signature algorithm.
sign_method	String	header	Yes	The signature digest algorithm. Set the value to HMAC-SHA256.
t	Long	header	Yes	The 13-digit standard timestamp.
access_token	String	header	Yes	The information about the token. Note: This parameter is not required when you make API requests to get or refresh tokens.
lang	String	header	No	The type of language. Set the value to zh for the service that is deployed in mainland China and set the value to en for the service that is deployed in other regions outside mainland China.
nonce	String	header	No	The universally unique identifier (UUID) automatically generated after an API is created. Note: This parameter is not required when you use the earlier signature solutions.
Signature-Headers	String	header	No	The header field customized by you. Note: This parameter is not required when you use the earlier signature solutions.

Signature algorithm

For more information：Sign Requests
When you call an API operation of the Cloud Development Platform, you must provide a signature to verify your identity.

Signature algorithm: Tuya uses HMAC-SHA256 to create a message digest.

1. Signature algorithm for token management operations:
   • Scope of application: operations that are used to get or refresh tokens.
   • Signature algorithm: sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()

2. Signature algorithm for service management operations:
   • Scope of application: operations that are used to manage services rather than tokens.
   • Signature algorithm:
   str = client_id + access_token + t + nonce + stringToSign
   sign = HMAC-SHA256(str, secret).toUpperCase()

3. stringToSign signature string

   • Components

   String stringToSign= 
   HTTPMethod + "\n" + 
   Content-SHA256 + "\n" +
   Headers + "\n" +
   Url
   

4. Signature examples
   For more information：Signature examples

5. Signature validation results
   You can use Postman to call and view Sign’s input parameters and encryption results：Verify Signature Result

Project API service management

API Lis：Cloud Services API Reference

This section describes the scope of API services available for different development methods (smart home projects and industry projects).

• Smart home PaaS system — API list：
  
• Custom development (industry SaaS system) - API list：
  

Postman call practice

For more information, see Set Postman Environment and Call API Operations.

API request sequence

Taking the smart home PaaS project as an example, call the devices under the app user and control the sending of instructions.

FAQ

1. Please refer to the document for equipment standard instruction set：Standard Instruction Set.
2. The sign_method in the request header is required. Otherwise, the cloud signature verification might have an error.
3. Signature-Headers can be empty, then the Headers in stringToSign is also empty. However, there are still tailing line breaks.
4. All the url parameter values concatenated in stringToSign have line breaks.
5. The calculation method of Content-SHA256 is SHA256 without an encryption key.

Message subscription

For more information,see Message subscription
When the device status changes, such as device registration, data reporting, and going offline, Tuya will send notifications of these changes.
Message Service is used to actively push the event data to external partners through Pulsar, which meets their demands for real-time and persistent messages.

Client example：

Demo programming language	Endpoint	Description
Java	Download here	Documentation
Golang	Download here	Documentation
C#	Download here	Documentation
Python	Download here	Documentation
Nodejs	Download here	Documentation

Technical support

Common concepts of cloud development

Common parameters of cloud development can help you get to know the Tuya ecosystem quickly.
For more information, see Common Parameters

Help center

The help center provides FAQs and solutions to common issues about Tuya and development links.
For more information, see Help Center.

Service & support

If you cannot get the answers you need in the help center, you can click the icon in the bottom-right corner and click Submit Question to submit a ticket on the Service & Support platform. Tuya’s professionals will get back to you as soon as possible.