API Reference

Auth & Tokens

Device login and token. After login, token and c-id must belong to the same session.

Device login flow

Client
https://<host>:<port>/init
Server

POST /init

HTTP request

c-id: clientId · body: empty

Hover or tap a field
1 / 7

sessionKey = Base64Decode(token). Both sides derive it during login; never send it as a Bearer token. Logout or revokeSession revokes the login session; changing the password does not.

Create an API Token in the device app’s Connections → API Tokens. Copy its clientId and token together. Delete that token to revoke it. Use Bearer only over HTTPS.

HTTP body encryption does not protect the downloaded web code. First use needs a trusted server identity; for browsers, use trusted HTTPS.

If too many unauthenticated connections are open, the server returns HTTP 429 with an empty body before upgrading to WebSocket. Try again later.

WebSocket /auth · AuthErrorCode · Errors

First frame: 10 s. After the first valid frame: 60 s to finish the handshake. Total login/approval: 300 s.

INVALID_LOGIN_REQUEST
Check the login request format and start a new handshake.
PASSWORD_SETUP_REQUIRED
Set a login password on the device first.
INVALID_PASSWORD
Check the password and try again.
PEER_IDENTITY_CHANGED
Verify the device identity before continuing.
REMOTE_ACCESS_DISABLED
Enable remote access on the device.
REJECTED
The device owner rejected the login.
TIMEOUT
Start a new login request.
TOO_MANY_LOGIN_ATTEMPTS
Wait before trying again.

Operations

http

Bearer API token

Use a separate API Token to send JSON over HTTPS without body encryption.

bash
curl --request POST \
  --url 'https://<device-host>:<https-port>/graphql' \
  --header 'c-id: <client-id>' \
  --header 'Authorization: Bearer <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"{ app { deviceName capabilities access } }"}'
mutation

logout

Revoke the calling client's current authenticated session.

graphql
mutation logout {
  logout
}