Each StarLeaf Cloud endpoint runs an HTTP server and supports HTTP 1.0 and 1.1.

You may prefer to use HTTP 1.1 because it allows multiple requests per connection to the server.

The HTTP connection uses port 23456.

IP authentication

To use this API over an IP connection, you must first authenticate.

To authenticate:

  1. Fetch the path /auth, which returns a JSON object.
  2. Extract the salt and iterations fields.
  3. Convert the salt (which is a hex string) to binary.
  4. Derive the key from the password along with the salt and iterations

    key = PBKDF2(HMAC-SHA256, password, salt, iterations, 256)

  5. Derive the response from the derived key and the challenge field:

    response = HMAC-SHA256(key, challenge)

  6. Fetch /auth again, with challenge and response as arguments.
  7. If successful, the boolean field authenticated in the returned object is true and string field session is present.

Refer to Example Python key derivation script for an example of how to derive the key.

When authentication is successful and the session value obtained, it can be provided as a parameter to all future requests requiring that authentication level.

A session lasts indefinitely while in use, but times out one hour after the last request. A challenge string times out after one minute, and can only be used once (after making an incorrect response, a new challenge must be fetched to try again).

Note that the salt and iterations fields are constant for each set password, so the key need only be derived once.

HTTP cookies

The returned session field when authenticating is also set as a session cookie, allowing browser-style clients to make use of the authenticated state without further effort.

Fetching the path /auth with no parameters (other than the cookie) returns the above object indicating whether the user is authenticated.

Sending requests over IP

Use either POST and JSON or GET/HEAD and URI queries.

If you are connecting over IP, any request can be given the additional boolean option pretty to enable pretty-printing of the JSON output. This adds whitespace to make the output easier to read while not changing semantics.

Using POST and JSON queries

The request parameters are supplied in JSON format as the body of a HTTP POST request.

For example:

POST /action HTTP/1.0
  "action": "dial",
  "number": "1234"

Using GET/HEAD and URI queries

The request parameters are rendered inside the GET or HEAD query string.

For example:

HEAD /action?action=dial&number=1234 HTTP/1.0

Query values can only contain integers, strings and true boolean values. Integers and strings are passed directly (no quoting is required with strings). Boolean values are set by passing them without any value. Boolean values cannot be set to false through this interface – if that is required, JSON must be used instead.

HEAD /action?action=audio_mute&on HTTP/1.0