Authentication API

The authentication methods create and revoke login sessions, report the authenticated identity and issue one-time tokens for the WebSocket event channel. A session is an alternative to sending the login and password with every request: it is created once by login and then identifies the user through the astra_session cookie or an Authorization: Bearer header, as described in How to call API methods.

Login

Request: POST /control/

Served without prior authentication: the command document is the credential.

{
    "cmd": "login",
    "login": "...",
    "password": "...",
    "remember": false
}

• login - string, required. User login from the users table.
• password - string, required. Plain password.
• remember - boolean, optional, default false. true creates a session that survives the browser session.

The credentials are checked against the users table the same way as Authorization: Basic: the user must exist, must not be disabled, and must have type 1 (control) or 2 (observer).

Response:

{
    "login": "admin",
    "type": 1
}

• login - the authenticated login
• type - 1 for control, 2 for observer

The reply carries the session cookie:

Set-Cookie: astra_session=<session id>; Path=/; HttpOnly; SameSite=Lax

• astra_session - the session id, 64 hexadecimal characters. The same value works in an Authorization: Bearer <session id> header.
• Path - the control path (/ by default, /ctl/ with control_path set to ctl).
• HttpOnly; SameSite=Lax - always set.
• Secure - added when the request came over HTTPS.
• Max-Age=2592000 - added when remember is true (30 days). Without remember the cookie has no Max-Age and is dropped when the browser session ends.

On the server side a session is valid for 24 hours, or 30 days with remember. One login holds at most 16 sessions: creating another one drops the session closest to expiry. Sessions are stored in sessions-<port>.json in the Astra data directory (/var/lib/astra, or ~/.local/state/astra when the former is not writable) and survive a restart. Only the login is stored: the user type and enabled state are read from the users table on every request, so disabling a user or changing its type applies to its live sessions immediately.

Error replies:

• 400 - the command document does not carry the string fields login and password. The reply body is empty.
• 403 - unknown login, wrong password, disabled user, or a user of type 3. No cookie is set. An unknown login, a wrong password or a disabled user writes [main] Authentication failed. Login:<login> IP:<address> to the log; a user of type 3 is rejected without a log line.
• 429 - too many failed password checks from this address: 5 failures within 60 seconds lock the address until 60 seconds pass since the last failure.

Example:

curl -c cookies.txt -X POST \
    -d '{"cmd":"login","login":"admin","password":"secret","remember":true}' \
    http://server:8000/control/

Logout

Request: POST /control/

{
    "cmd": "logout"
}

Requires authentication. Revokes the session that authenticated the request (the astra_session cookie or the Bearer session id) and expires the cookie. A request authenticated with Authorization: Basic has no session to revoke; the reply is the same.

Response:

{}

With the header:

Set-Cookie: astra_session=; Max-Age=0; Path=/; HttpOnly; SameSite=Lax

Other sessions of the same login stay valid. A user’s sessions are all revoked when the user is disabled with toggle-user, removed, or its password is changed (see Users API).

Example:

curl -b cookies.txt -X POST -d '{"cmd":"logout"}' http://server:8000/control/

Who am I

Request: POST /control/

{
    "cmd": "whoami"
}

Requires authentication with any credential. Returns the identity the request was authenticated as; a web interface uses it to restore the logged-in state from the cookie and to pick the control or observer view.

Response:

{
    "login": "admin",
    "type": 1
}

• login - the authenticated login
• type - 1 for control, 2 for observer

Example:

curl -b cookies.txt -X POST -d '{"cmd":"whoami"}' http://server:8000/control/

WebSocket token

Request: POST /control/

{
    "cmd": "ws-token"
}

Requires authentication. Issues a one-time token bound to the authenticated identity. The token is the credential of the WebSocket handshake on {control_path}control/event/, the channel that pushes configuration changes and status updates to the web interface (see Events): a browser cannot add an Authorization header or a custom cookie to a WebSocket handshake, so the token is passed in the URL instead.

Response:

{
    "token": "..."
}

• token - 64 hexadecimal characters

The token:

• is valid for 60 seconds after it was issued;
• is redeemed once: the first handshake with it consumes it, a second one is answered 403;
• is never written to disk and does not survive a restart;
• is revoked when its user is disabled or removed before the handshake. One login holds at most 16 unredeemed tokens.

Usage:

GET {control_path}control/event/?token=<token>
Upgrade: websocket

A valid token admits the connection into the broadcast set. An invalid or already used token is answered 403 with the HTML error page. A handshake without a token is accepted but receives no events: it serves liveness checks only (a text frame ping is answered pong, any other frame closes the connection with code 1008).

Example:

curl -b cookies.txt -X POST -d '{"cmd":"ws-token"}' http://server:8000/control/

Disabled authentication

With the --no-web-auth command line option the control server does not check credentials. Every request, including one without any credential, is authenticated as login - with type 1:

• login answers {"login": "-", "type": 1} without a Set-Cookie header; the body is still parsed and must be a JSON object with login and password.
• whoami answers {"login": "-", "type": 1}.
• logout answers {} and the clearing cookie.
• ws-token still issues a token, but the WebSocket handshake admits every connection, with any token or none.