Skip to main content

Authentication

The REST API uses bearer tokens. Call /api/displaynet/login with a user name and password to obtain a token. Send that token with subsequent requests.

The token is the same LoginToken returned by the login command and used by the web interface. The identity is the same across all three interfaces. The token authorizes both DisplayNet API and SDVoE API requests.

Token requirement​

Whether a token is required depends on how the server is configured.

Server settingRequests without a token
Authentication requiredRejected with 401
Authentication not requiredAccepted, and treated as the built-in DisplayNet user

The telnet interface follows the same rule; see Connection State.

Do not depend on unauthenticated access

A client that skips login works only while authentication is disabled. It stops working when an installer enables authentication. Send a token unless you control the deployment and know authentication will remain disabled.

Sending a token always works, whichever mode the server is in.

Obtaining a token​

Request​

POST /api/displaynet/login
Content-Type: application/json

{
  "user": "DNAdmin",
  "password": "<password>"
}

Response​

{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "token": "<login token>",
    "user": "DNAdmin",
    "role": "Admin",
    "expires_days": 30
  },
  "error": null
}
FieldDescription
tokenThe bearer token to send on subsequent requests
userThe authenticated user name
roleThe user's role, which determines what they may call
expires_daysToken lifetime in days, from the server's login-token expiry setting

Bad credentials return 401 with reason AUTH_FAILED. A missing user or password field returns 400 with reason ILLEGAL_ARGUMENT.

Using the token​

Send it as a bearer token in the Authorization header:

Authorization header​

Authorization: Bearer <login token>

The server ignores an Authorization header that uses another scheme. It treats that request as unauthenticated.

Query parameter for WebSocket clients​

A token may also be supplied as a token query parameter:

wss://<server>/api?token=<login token>

Browser WebSocket clients cannot set request headers, so they can use this query parameter instead. Use the header everywhere else. Tokens in URLs are more likely to appear in logs or proxy history.

Roles​

Every operation has a minimum role. The OpenAPI spec exposes it as x-displaynet-min-role, so a generated client can check the requirement before making the call. The server rejects a token whose user does not meet that requirement with Permission Denied.

Revoking a token​

REST requests do not keep a server-side session open. To invalidate a token before it expires, call the logout operation:

POST /api/displaynet/logout
POST /api/displaynet/logout
Authorization: Bearer <login token>

This invalidates the presented token. It has the same effect as user invalidatemylogintoken on the telnet interface. Logging out without a valid token returns 401.

A token remains valid until it expires. A long-lived integration can reuse one instead of logging in for every request.

See also​