Start

The console and the API

The web console is part of the binary and is only a client of the REST API. Whatever it does, a script can do; whatever a script can do, it shows.

Reaching the console

Open http://127.0.0.1:8080/ and sign in with a token. Nothing is loaded from the internet: the pages, their scripts and their fonts are in the binary. The token is kept for the browser tab only and forgotten when the tab closes.

From another machine, tunnel rather than open the port:

$ ssh -L 8080:127.0.0.1:8080 server
# then browse to http://127.0.0.1:8080/

To publish it properly, serve it over HTTPS: -api-tls-addr 0.0.0.0:8443 gives a second listener with the server's own certificate, which the browser phone needs anyway. Or put a reverse proxy with TLS in front. The token must never travel over plain HTTP on a network.

Behind a reverse proxy, name it: -trusted-proxy 127.0.0.1, or its network. The proxy's X-Forwarded-For is then believed, from it and nobody else, so that login rate limiting and the audit log see each person's own address. Without it everybody looks like the proxy, and five wrong passwords by one person would lock out all.

Tokens

The first token is printed at the first start. Make more under Security → New token, or with the API:

$ api -d '{"name":"deploy"}' localhost:8080/v1/tokens
$ api -d '{"name":"wallboard","scope":"read"}' localhost:8080/v1/tokens

A token is shown once; the server keeps a hash. A read-only token ("Only look" in the console) is for a wallboard, a monitoring system or a colleague who should only watch: it can read everything except secrets, which means not the configuration export, not recordings or voicemail audio, and of a webhook URL only the host it points to. It changes nothing.

Users who sign in

Users can sign in too, with their extension and a console password you give them (Users → the user → Password for this console, or "portal_password" in the API; "auto" has one made and returned once). It is not the SIP password, which belongs in the phone and nowhere else. They get their own pages, served under /v1/me, which takes the extension from the session so there is no way to reach somebody else's:

their forwarding and do-not-disturb,
their voicemail, to listen to and delete,
their calls,
their password,
and the Phone page, a softphone in the browser.

Sessions last 12 hours. Five wrong passwords lock that extension out from that address for a quarter of an hour; a hundred from all addresses together lock it out from everywhere, though a token still works. Changing or removing the password signs the user out everywhere. What they change appears in the audit log as user 1002.

Administrators

A user can be an administrator (Users → Administrator of this server, or "admin": true). Signed in with their extension they have everything an admin token has, plus their own pages, and the audit log names them. Their console password must have at least 12 characters. The role is looked up with every request: untick it, or disable the user, and it is gone at once. Tokens remain what scripts use, and the way back in if everybody forgets their password.

The audit log

Security → Changes, or GET /v1/audit, lists who changed what: every change through the API or by a feature code from a phone, and every refused attempt, with the token's name or the user's extension and the address it came from. What was sent is never recorded, so a password does not end up in the log.

Talking to it with curl

Every answer is one envelope: success, data and error. Errors name the field and the reason and never echo the value, since it may be a password. Lists take limit and offset and carry meta.total. A PUT replaces, a PATCH changes the fields you send. The API page lists every resource; the console's forms are the same fields.

$ api localhost:8080/v1/users/1
{"success":true,"data":{"id":1,"username":"1001","display_name":"Alice","voicemail":true,…},"error":null}

A whole configuration can be exported and imported as one JSON document, GET and PUT /v1/config: users, trunks, routes, groups, menus, settings, passwords included. It is a complete backup of the configuration and a way to move it between servers; the data (call records, voicemail, the audit log) is in the database backups instead.

← Installation Users and phones →