Integrating Xiaomi ecosystem devices into third-party automation systems such as Home Assistant requires a unique security identifier.This key, often referred to as a token, acts as a digital pass allowing the local controller to exchange commands with the gateway without the mediation of cloud servers. Without this parameter, direct interaction with the device via the miio protocol is impossible, making its extraction a critical first step for advanced users.
Many owners of smart homes face difficulties at the stage of extracting this data, since the manufacturer does not provide them explicitly in the standard Mi Home application. The process of obtaining the Xiaomi Gateway token can vary depending on the operating system of your smartphone and the version of the software used. In this article, we will discuss in detail the current authorization methods that will allow you to fully unlock the potential of your devices.
It is worth noting that the procedure requires attention to detail and the exact following of the instructions steps. An error in one character when entering data or skipping the setup step will make it impossible to connect. A token is a string of 32 hexadecimal characters that is generated individually for each device when first associated with an account. Understanding the nature of this key will help avoid common errors when setting up integration.
Why you need a token for the Xiaomi gateway
The communication protocol used by Mijia and Aqara devices is designed with a focus on security and energy efficiency. To protect against unauthorized access, every command sent to or from the gateway must be signed and encrypted. The token serves as the basis for generating encryption keys, ensuring the integrity of the data transmitted between your phone or automation server and the device itself.
Using the token allows local management, which is critical to system response speed. When you click a button in the Home Assistant app, the command goes directly to your network, bypassing servers in China or Europe, which means that even without the Internet, your scripts will continue to work, and the delay in execution of commands will be minimal.
⚠️ Warning: Never give your token to third parties or publish it publicly.The token owner gains full control of the device on your local network, which can lead to a leak of presence data or unauthorized access.
In addition, the token provides access to hidden gateway functions that are not available in the standard interface, so you can configure complex logic chains, receive advanced telemetry data, and integrate the gateway with dozens of other platforms, turning a simple whistle into a powerful control center for the home.
Preparation for the removal of the security key
Before you start technical manipulation, you need to make sure your environment is ready to go, you need a smartphone with the Mi Home app installed and an account with the gateway attached to it, and it is important that the device has already been successfully added to the application and worked correctly through the standard interface.
To perform the procedure on your computer, you will need Python version 3.7 or higher installed. This is a cross-platform programming language that allows you to run specialized scripts to interact with the Xiaomi API. If you have not previously worked with the command line, do not worry: all commands will be presented in a ready-made form.
Also make sure your computer and gateway are on the same subnet, which means they have to be connected to the same router or switch. If you use a guest Wi-Fi network or AP Isolation on a router, the process will not work because the devices will not be able to see each other.
☑️ Test of preparedness for procedure
Retrieval method through Python and Miio
The most versatile and reliable way to obtain a token is to use the python-miio library, which works independently of your computer’s operating system and the gateway firmware version, as it is based on the analysis of network traffic between the official application and the server.
The first step is to install the library itself. Open the terminal or command line and enter the installation command via the pip packet manager. Make sure you have administrator privileges to install software packages.
pip install python-miioOnce successfully installed, we move on to the authorization process itself. The miio library has a built-in tokenization utility that emulates the login to your Xiaomi Cloud account. You will need to enter your login (phone number or email) and password from your Mi Account account.
Follow the following command by replacing the data with your own:
Miio token --username your Login --password your passwordThe system will try to get a list of all devices associated with your account and display them. IP-address, MAC-Addresses and, most importantly, tokens, find your gateway by the name of the model or token. IP-address and copy the corresponding string of the token.
What to do if the entrance is blocked?
Alternative ways for Android and iOS
If using the command line seems too complicated for you, there are graphical techniques that are especially popular with Android users. One of the most famous tools is a modified version of the Mi Home app or specialized tokenizer utilities available in the development communities.
For iOS users, the situation is more complicated because of the system's closedness, but there is a method that does not require jailbreaking, but requires a profile to be installed to intercept the system. SSL-This is a more risky route, requiring trust certificates to be installed on the device.
Let us consider the main differences in the approaches in the table below:
| Parameter | Python Miio | Android utility | SSL Sniffing (iOS/Android) |
|---|---|---|---|
| Difficulty | Medium | Low. | Tall. |
| I need a PC. | Yes. | No. | Yes (for Proxy) |
| Security | Tall. | Medium | Low. |
| Relevance | Always. | Depends on the version. | Depends on the certificates |
When choosing a method for Android, remember that downloading modified APK-Files from unverified sources carry risks. Always check files with antivirus and use only trusted repositories such as GitHub or XDA Developers.
💡
Use an Android virtual machine or emulator (like BlueStacks) tokenize to avoid compromising the security of your main smartphone with personal data and passwords.
Set up Home Assistant after receiving the token
Once you have the cherished character string, you can move on to integration. In Home Assistant, this process is as automated as possible. Go to Settings, select Devices and Services, and click Add Integration.
In the search, type in Xiaomi Miio. The system will prompt you to enter IP-The address of the device and the token received earlier, you may also need to specify the model of the gateway, if it is not determined automatically, M1S, M2 others.
Once you enter, click send. If the token is true and the device is available online, Home Assistant will create a new device. Depending on the gateway model, you will have access to light sensors, control sensors. RGB-Illumination, dynamics and status of connected ZigBee devices.
⚠️ Note: When you change your Wi-Fi router password or reset the gateway to factory settings, the device token will change. You will have to re-extract and update the integration in Home Assistant.
It is important to properly adjust the static IP-If the address of the device changes after the router restarts, the integration will stop working, and you will have to change the settings manually. IP down MAC-Address – a mandatory step for the stable operation of a smart home.
Addressing common problems
Often users encounter an error called "Invalid token" or "Device offline." The first error indicates that the copied string contains extra spaces or characters. Make sure you copy exactly 32 characters without spaces at the beginning and end of the line.
The second problem is usually with the network screen or router settings: Make sure port 54321 (standard for Xiaomi devices) is open to the local network. Some routers with IoT Protection feature can block local requests to smart devices.
If the gateway is re-shooted or reset, the old token becomes invalid, in which case reuse of the old data is useless, you need to re-add the device to the Mi Home application and re-extract the new token, as a new pair of keys is generated when you reset.
💡
The stability of a smart home is 90% dependent on the correct network setup and static IP, not just the presence of a token.
In rare cases, Xiaomi servers can temporarily block frequent authorization requests from one user. IP-If you get a network error, pause for a moment. 15-30 minutes before you try again. Don't try to run a tokenization script in a loop without delay.
Security and key updates
Although the token gives full access to the device, compromising it within the local network is less dangerous than leaking a password from a Mi Cloud account. However, an attacker who gained access to your Wi-Fi network could theoretically intercept the token if traffic is not additionally protected.
To improve security, it is recommended to create a separate VLAN network for smart home devices, isolated from your personal computers and smartphones, in which case, even if you break into a light bulb or gateway, the attack will not be able to spread to your basic data.
Regularly update the gateway firmware through the official app. Xiaomi engineers periodically close vulnerabilities in the protocol, making old tokenization methods non-working, but increasing the overall security of your network.