The Teamline system runs an HTTP server and supports HTTP 1.0 and 1.1. HTTP 1.1 may be preferable because it allows multiple requests per connection to the server. The HTTP connection uses port 80.

IP authentication

Before you can use this API over an IP connection, you must authenticate.

To find the password (the ECAPI key) in Maestro, click Manage next to the relevant meeting room and in the Touch Panel tab, click Edit then enable Enable ECAPI . The ECAPI key is displayed.

To authenticate:

  1. Fetch the path /ecapi/auth. A JSON object is returned.
  2. Extract the salt and iterations fields.
  3. Convert the salt hex string to binary.
  4. Derive the key from the password with the salt and iterations:
  5. key = PBKDF2(HMAC-SHA256, password, salt, iterations, 256)

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

    response = HMAC-SHA256(key, challenge)

  7. Fetch /ecapi/auth again, with challenge and response as arguments.

If successful, the boolean field authenticated in the returned object is true and string field session is present.

For an example of how to derive the key, refer to Example Python key derivation script.

When authentication is successful and the session value is 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.

The salt and iterations fields are constant for each set password; the key is only 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.

Fetch the path /ecapi/auth with no parameters (other than the cookie) to return the above object, indicating whether or not 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 option 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 /ecapi/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 /ecapi/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; quoting is not required with strings. Boolean values are set by passing them without any value. Boolean values cannot be set to false through this interface. If this is required, JSON must be used instead.

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