Skip to main content
← Back to pricingHelp guide

Licensing guide

Everything about the TuyaOpen authorization code: what it is, which tier your device needs, how to claim or buy one, write it, verify it, and fix the common issues.

What is a TuyaOpen license?

A TuyaOpen license is the credential that lets one device connect to the Tuya IoT Cloud. It is two strings, issued by Tuya and bound to your product:

  • UUID — a 20-character identifier, unique to each device.
  • AuthKey — a 32-character key paired one-to-one with the UUID.
When do you actually need one?

Only when your application uses Tuya Cloud services — cloud connection, app control, OTA, or AI. Local-only and offline projects (Bluetooth, Wi-Fi, third-party APIs) run on the free open-source framework with no license at all.

TuyaOpen licenses are not TuyaOS licenses

TuyaOpen requires a TuyaOpen-specific UUID + AuthKey. Licenses from TuyaOS (or other sources) cannot connect to the cloud within the TuyaOpen framework.

Which tier does your device need?

Match the tier to what the device does. You can always start free, then write a paid license later — the framework and code stay the same.

Open Source
Free

Local control, Bluetooth/Wi-Fi, sensors, third-party APIs. No cloud, no license.

IoT Connection
¥5

Tuya Cloud connection, Smart Life app control, data points, and OTA updates.

AI + IoT
¥12

Everything in IoT, plus voice (ASR/TTS), LLMs, vision, and the AI agent platform.

See the full comparison →

Get a license

For development you can claim free codes; for production you buy per-device licenses.

Claim 2 free developer licenses

During development you can claim 2 free device licenses (¥20 value) from the Tuya Developer Platform:

  1. Log in to the Tuya Developer Platform and create a product — pick any category (it is only a starting template). For AI-Agent features, choose an AI-tagged template.
  2. Select the T5 module, click Add Custom Firmware, and upload any dummy file as a placeholder.
  3. On the product page, click to claim 2 free authorization codes.
  4. Open the License list to find your UUID and AuthKey.
Open the Developer Platform

Buy production licenses

When you are ready to ship, buy per-device licenses (¥5 IoT / ¥12 AI + IoT). You can also order Tuya modules pre-flashed with a license at the factory.

Buy licenses

Write the license to a device

Once you have a UUID + AuthKey, write them with whichever method fits your workflow. All four do the same thing.

Recommended

Header file (bake into firmware)

Set the macros in tuya_config.h (in your project’s src or include directory), then rebuild and flash. Best for permanent, per-build configuration.

// tuya_config.h
#define TUYA_OPENSDK_UUID    "uuidxxxxxxxxxxxxxxxx"  // your UUID
#define TUYA_OPENSDK_AUTHKEY "keyxxxxxxxxxxxxxxxxxx"  // your AuthKey

# then:
tos.py build && tos.py flash
Serial CLI

auth command over serial

For firmware that supports the auth CLI. Open the serial monitor on the flashing port, write the pair, and reboot.

tos.py monitor -b 115200

tuya> auth uuid9f6a6... cGuDnU2Yxj...
Authorization write succeeds.
GUI

tyutool desktop app

Connect the device, open the Authorize tab, enter the UUID + AuthKey, and write — no rebuild required. Great for one-offs and small batches.

tyutool →
Browser

TuyaOpen Serial Web Tool

In a Chrome-based browser, open the web tool, connect to the authorization port, and use the authorization-write tab.

tuyaopen.ai/tools/ →

On MCU, writing the license once is enough — it is stored in a non-application key-value area, survives firmware updates, and is only lost on a full flash erase or when writing a new key.

On SoCs with a filesystem (Linux, Raspberry Pi) the license can be compiled into a header or kept in a file and loaded at runtime.

Verify & pair the device

Confirm the license is stored, reboot, then bring the device online in the app.

  1. Read the stored license back with the auth-read command and confirm the UUID and AuthKey are the real values (not xxxx).
  2. Reboot the device for the authorization to take effect.
  3. Pair the device in the Tuya Smart Life app. It activates against the cloud using the credentials.
tuya> auth-read
uuid9f6a6xxxxxxxxxxx
cGuDnU2YxjHJldjxxxxxxxxxxxxxxxxx
One UUID, one online device

Each UUID brings a single device online at a time. To reuse the AuthKey on another board, first unpair the original device in the Tuya app (device panel → Unbind and Clear Data).

Troubleshooting

Logs show “Authorization read failure” on boot

The license was never written, or was written incorrectly. Re-write the UUID + AuthKey using one of the methods above, then reboot.

auth-read shows xxxxxxxx instead of real values

No authorization is stored. Write it with the auth command or the header file, then reboot and read it back to confirm.

The device won’t pair / isn’t found in the app

Verify with auth-read that real UUID/AuthKey are stored and that they are TuyaOpen (not TuyaOS) licenses with the correct PID. Re-write if needed, reset the device, and try pairing again. On Linux, delete the tuyadb folder and re-run.

Can I move a license to a different device?

Yes, but only after unpairing the original device from the Tuya app. One UUID can have only one device online at a time.

Does flashing new firmware erase my license?

No. On MCU the license sits in a protected key-value area and survives firmware updates. It is only cleared by a full flash erase.

More help

These docs go deeper on each step:

For enterprise, volume, or custom pricing, contact service@tuya.com.