Skip to content

HTTP APIs

Jump to bottom
Alberto Geniola edited this page Jan 19, 2019 · 7 revisions

HTTP API

The Meross app talks directly with a HTTP API endpoint when the user firstly register. So far, it seems that the API offer the following methods:

  • Login
  • Device listing
  • App usage tracing (TBD)
  • Register (TBD)

Common message structure

Every message posted to the Meross HTTP endpoint must be sent via HTTP POST method. The payload should be in JSON format and, and should comply with the following JSON structure:

{"params": "<method_parameters>", "sign": "<md5hash>", "timestamp": 0, "nonce": "<nonce_value>"}

Where:

  • <method_parameters> is the base64 representation of the json data that the method expects as parameters.
  • <token_acquired_via_login> is a placeholder for the token acquired via the login request
  • 0 is the current timestamp in milliseconds. This should not be 0, but the current timestamp (integer value)
  • A nonce value, randomly generated as a 16 aplhanumeric sequence (digits and upper case letters)
  • is the base64 encoded MD5 digest of the concatenation of:
    • The constant string: "23x17ahWarFH6w29"
    • The timestamp
    • The nonce value
    • The method parameters

Moreover, a number of HTTP-headers should be included in order to let the web-server accept our request:

Authorization: Basic <token_acquired_via_login>
Content-Type: application/json
vender: Meross
AppVersion: 1.3.0
AppLanguage: EN
User-Agent: okhttp/3.6.0

Login

The login operation aims at exchanging the user's credentials for some tokens that can be later used for both HTTP API and for the MQTT broker authentication.

The <method_params> should be build by converting the following json object into Base64 string:

{"email": "YOUR_EMAIL", "password": "YOUR_PASSWORD"}

Assuming that the email is "[email protected]" and the password is "root", here is how we build the request:

  1. Base64 Encode the payload {"email": "[email protected]", "password": "root"}

    eyJlbWFpbCI6ICJtZUBnb29nbGUuY29tIiwgInBhc3N3b3JkIjogInJvb3QifQ==

  2. Prepare the clear string to sign, by concatenating the SECRET string, the timestamp in milliseconds, a random nonce(16 chars) and the base64-encoded parameter string.

    23x17ahWarFH6w29 + 0 + 0123456789ABCDEF+ eyJlbWFpbCI6ICJtZUBnb29nbGUuY29tIiwgInBhc3N3b3JkIjogInJvb3QifQ==

    23x17ahWarFH6w2900123456789ABCDEFeyJlbWFpbCI6ICJtZUBnb29nbGUuY29tIiwgInBhc3N3b3JkIjogInJvb3QifQ==

  3. Calculate the MD5 hash of that string. Note! The md5 value must be used in LOWER case, otherwise it won't work

    e9be76eaa17e837b81d6bca558028a23

So, the request would be:

POST /v1/Auth/Login HTTP/1.1
Host: iot.meross.com
Authorization: Basic
Content-Type: application/json
vender: Meross
AppVersion: 1.3.0
AppLanguage: EN
User-Agent: okhttp/3.6.0

{"params": "eyJlbWFpbCI6ICJtZUBnb29nbGUuY29tIiwgInBhc3N3b3JkIjogInJvb3QifQ==", "sign": "E9BE76EAA17E837B81D6BCA558028A23", "timestamp": 0, "nonce": "0123456789ABCDEF"}

Successful Response:

{"userid": "XXXX", "email": "[email protected]", "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXX"}

There are three interesting parameters returned by the login request:

  • userid: the user id associated to a specific email address. Internally, email is never used except for login purposes.
  • token: access token for HTTP API.
  • key: access token used in MQTT communication

Device listing

This endpoint is used by the application in order to list all the devices that have been paired by the user. So, by quering this endpoint, you'll get all the devices associated to your account.

Request:

POST /v1/Device/devList HTTP/1.1
Host: iot.meross.com
Authorization: Basic <token_acquired_via_login>
Content-Type: application/json
vender: Meross
AppVersion: 1.3.0
AppLanguage: EN
User-Agent: okhttp/3.6.0

{"params": "e30=", "sign": "<md5hash>", "timestamp": 0, "nonce": "<nonce_value>"}
Clone this wiki locally