AqaraLink Developer Platform Getting Started: Zero to First Call

Answer up front — The documented path is six steps: register a developer account, create a project (yielding an appId and a key), choose an authorisation mode, onboard devices, call the API, then configure message push and an IP whitelist. The authorisation choice shapes everything after it. Aqara account binds a real user's Aqara Home devices. Project authorisation is for B-side estates onboarded through the Implementation Tool. Virtual account creates an Aqara account for your own end user so your app never asks them to sign up twice — and that virtual account cannot be used in Aqara Home, only through the SDK.

Our AqaraLink developer platform overview covered what the platform is and which modules exist. This post is the first week of building on it: the order of operations, and the branch you have to pick in week one.

The six steps the documentation actually lists

The English developer docs at opendoc.aqara.com set out the cloud integration process in a fixed order. Follow it literally — two of the steps depend on configuration the previous one creates.

1. Register and log in to the Aqara developer platform.
2. Create an application and a key. New project → fill in Project Name, Industry Type, Introduction → Save. The project appears as pending review; once approved the status changes to approved and project details become viewable. The appId is assigned to the project, and on approval a default key is generated, visible under Project Details → Key Management, where you can add more.
3. Authorisation management. Three modes, covered below.
4. Add device. Three routes, chosen "according to the developer's needs and authorisation type".
5. API management. Query device information, control devices, configure linkage.
6. Message push configuration, plus optional IP settings.

Two facts from that list get skipped and cause pain later. First, a project is not usable until it is approved. Second, user and device data are isolated between projects, but the same user can be authorised to multiple projects. A project per client therefore does not isolate tenants in any meaningful sense; it multiplies the credentials you have to rotate.

Step 3 is the real decision: which authorisation mode

This is the branch. It is cheap to read, expensive to change after your onboarding UX is written.

The "Visible in Aqara Home" row is the whole point of the virtual account mode, and the constraint in bold is the part that catches teams out.

Virtual accounts: what they are and what they are not

The documentation is blunt about the motivation. A developer who already has an account system, and wants to bring Aqara devices into their own IoT ecosystem without the end user perceiving two sets of accounts, integrates the Aqara device SDK in their own app and binds devices to a specified virtual account. A virtual account is defined as a virtual Aqara account created through the interface, against which a user can bind devices through the open SDK or the implementation tools.

For an integrator building for a client:

• You own the identity. Your accountId — a string you create, guaranteed unique under the appId — is the root. Your client never creates an Aqara account and never needs to know one exists. The platform returns an openId, the unique identifier for the virtual user, which is the handle your backend stores and uses in every subsequent call.
• Token validity is yours to set. config.auth.createAccount takes an optional needAccessToken boolean — false returns just the openId, true also returns accessToken, refreshToken and expiresIn. The optional accessTokenValidity defaults to 7 days and accepts 1–24 hours or 1–30 days. The refresh token is valid until the access token's expiry plus 30 days.
• Virtual accounts cannot be used in the Aqara Home app. If your end user also uses Aqara Home, they will not see the devices you bound. Decide early whether that is acceptable, because it cannot be reversed by support.

The documented sequence, in shape

Step 1 — create the virtual account:

`` { "intent": "config.auth.createAccount", "data": { "accountId": "18900001234", "remark": "lumi-1" } } ``

Step 2 — request an authorisation code with accountType 2 for virtual account. The code is valid for 10 minutes. Step 3 — exchange it with config.auth.getToken for accessToken, refreshToken, expiresIn and openId.

The real Aqara-account path follows the same shape from a real account: config.auth.getAuthCode with accountType 0, code valid 10 minutes, then config.auth.getToken, whose access token defaults to 7 days. Project authorisation is the same exchange with accountType 1 and a code from the IoT Solution Platform console. config.auth.refreshToken handles renewal, and all three return tokens on the same terms — refresh validity is the access token's expiry plus 30 days, a hard ceiling on how long a forgotten refresh can sit.

Check the current parameter names and account-type values against the live authorisation management page before you hard-code them. The docs are versioned separately from your integration.

Every request is signed — the part you cannot skip

Calls go to https://${domain}/v3.0/open/api, where the domain is a server area. The docs list deployed regions including China mainland, United States, South Korea, Russia, Europe and Singapore, each with its own API domain and timezone, selected on the project. Required headers: Appid, Keyid (the key of your app), Nonce (a random string, different for every request) and Time. Accesstoken is present where the interface needs it.

The sign rule, verified from the signature rules page: sort the header parameters by ASCII and splice as Accesstoken=xxx&Appid=xxx&Keyid=xxx&Nonce=xxx&Time=xxx, append the Appkey directly to that string, lowercase the result, then MD5, 32-bit. That is your Sign header.

One documented exception: some interfaces do not require Accesstoken, and in that case Accesstoken does not participate in the signature. Getting this wrong produces error code 106 Invalid sign, and 107 Illegal appKey catches a key you have not activated.

Step 4: three onboarding routes, not one

The without-UI SDK is narrower than people expect: it is only used to add the gateway device, with sub-devices then added through the write.device.openConnect interface. The with-UI SDK gives you Aqara-styled pages you can use directly or restyle. For Zigbee, onboarding is hub-driven — your app calls the cloud HTTP API to put the hub into pairing mode, and the hub discovers and binds the surrounding devices. One honest note from the docs: no download link for the App SDK is published on the developer platform, and the page directs developers with requirements to contact Lumi's overseas business team. Plan for that conversation before you plan a sprint.

Single home or whole estate: the scoping decision

For a client's home you want a project, an IP whitelist, and the Implementation Tool or SDK for a handful of devices. For a whole estate you are in project authorisation on the Aqara IoT Solution Platform, with the Implementation Tool handling batch addition and a project authorisation code exchanged for a token.

The scoping question is not "how many devices" — it is "whose identity holds the devices when the contract ends." Under a virtual account, your client's devices sit in accounts you created, and when that client leaves the estate has to be migrated, not decommissioned. Under project authorisation, the estate sits inside your project and the devices come with the space design. Write down who can trigger a token refresh, because that person effectively controls the devices.

First-run checklist

• [ ] Project status reads approved, not pending review
• [ ] appId recorded, default key visible under Key Management
• [ ] Server area chosen; API domain and timezone noted
• [ ] IP whitelist populated — it is empty by default, so any IP can call your interfaces until you restrict it
• [ ] Authorisation mode chosen and written down
• [ ] Nonce generation confirmed non-repeating in your HTTP client
• [ ] Message push signature configured, or consciously left off
• [ ] Device debugging exercised — real devices under an authorised account, or virtual devices you add yourself (gateway first, then sub-devices)