Veyon WebAPI

Veyon 4.5 and newer feature a new WebAPI plugin. This plugin offers a RESTful API for accessing Veyon Server instances via HTTP. There are two possible usage scenarios:

  • Local: WebAPI server on each computer running along with the Veyon Server and thus connects to localhost
  • Proxy: WebAPI server on a server node, acting as a proxy by connecting to the requested hosts

While running the WebAPI server locally can be beneficial in terms of performance, it requires the deployment of individual SSL certificates on all computers.

The WebAPI plugins also offers a CLI module, so the WebAPI server can be run standalone easily via veyon-cli webapi runserver.

The following sections describe all supported API calls.

General

  • When a call succeeds, the indicated responses can be expected with HTTP status code 200.
  • Any errors will be indicated through a corresponding (non-unambiguous) HTTP status codes and an additional error object in the response body, e.g. {"error":{"code":6,"message":"Authentication failed"}}
Error Error code HTTP status code
NoError 0 200 (OK)
InvalidData 1 400 (BadRequest)
InvalidConnection 2 401 (Unauthorized)
InvalidFeature 3 400 (BadRequest)
InvalidCredentials 4 400 (BadRequest)
AuthenticationMethodNotAvailable 5 400 (BadRequest)
AuthenticationFailed 6 401 (Unauthorized)
ConnectionLimitReached 7 429 (TooManyRequests)
ConnectionTimedOut 8 408 (RequestTimeout)
UnsupportedImageFormat 9 503 (ServiceUnavailable)
FramebufferNotAvailable 10 503 (ServiceUnavailable)
FramebufferEncodingError 11 500 (InternalServerError)

Connection management & authentication

General

  • Idle (inactive) connections are closed automatically after 60 s per default (configurable through the WebAPI/ConnectionIdleTimeout setting)
  • Unauthenticated connections are closed automatically after 15 s per default (configurable through the WebAPI/ConnectionAuthenticationTimeout setting)
  • Authenticated connections have a limited lifetime and are closed automatically after 3 hours per default (configurable through the WebAPI/ConnectionLifetime setting)

Get authentication methods supported by host

  • URL: /api/v1/authentication/<HOST>
  • Method: GET
  • Response: { "methods": [ "<UUID1>", "<UUID2", ... ] }

Create new connection and perform authentication

  • URL: /api/v1/authentication/<HOST>
  • Method: POST
  • Data: { "method": "<AUTH-METHOD-UUID>", "credentials": <METHOD-SPECIFIC-CREDENTIALS> }
  • Response: { "connection-uid": "<CONNECTION-UID>", "validuntil": <UTC-TIMESTAMP> }
  • The returned connection UUID identifies a single connection to a host and needs to be passed in the Connection-Uid header field in all subsequent API calls
  • The connection’s lifetime ends at the time specified in the validuntil field
  • <HOST> should be localhost when connecting to WebAPI servers running on target computers

Close connection

  • URL: /api/v1/authentication/<HOST>
  • Method: DELETE
  • Headers: { Connection-Uid: <CONNECTION-UID> }
  • Response: { }

Authentication methods

Name UUID Credentials
AuthKeys 0c69b301-81b4-42d6-8fae-128cdd113314 { "keyname": "<NAME>" (e.g. "teacher"), "keydata": "<PEM-ENCODED-PRIVATE-KEY>" }
AuthLDAP (Veyon >= 5) 6f0a491e-c1c6-4338-8244-f823b0bf8670 { "username": "<LDAP-USERNAME>", "password": "<LDAP-PASSWORD>" }
AuthLogon 63611f7c-b457-42c7-832e-67d0f9281085 { "username": "<USERNAME>", "password": "<PASSWORD>" }
AuthSimple (Veyon >= 5) 73430b14-ef69-4c75-a145-ba635d1cc676 { "password": "<MASTER-PASSWORD>" }

Framebuffer

Get current framebuffer image

  • URL: /api/v1/framebuffer/get?format=[png|jpeg]&compression=[1-9]&quality=[1-100]&width=NNNN&height=NNNN
  • Method: GET
  • format
    • Optional
    • Defaults to png
  • compression
    • Optional
    • Used for the PNG format only
    • default=5
    • 1=no compression, 9=highest compression
  • quality
    • Optional
    • Used for the JPEG format only
    • default=75
    • 1=lowest quality, 100=highest quality
  • width/height
    • Optional
    • If none of both is not specified, the original framebuffer image will be returned
    • If either one is specified, the corresponding counterpart will be calculated automatically while keeping the aspect ratio
  • Response: <IMAGE-DATA>

Feature control

Get available features

  • URL: /api/v1/feature
  • Method: GET
  • Headers: { Connection-Uid: <CONNECTION-UID> }
  • Response: [ <FEATURE OBJECTS> ]

Start or stop feature

  • URL: /api/v1/feature/<FEATURE-UID>
  • Method: PUT
  • Data: { "active": [true/false] }
  • Headers: { Connection-Uid: <CONNECTION-UID> }
  • Response: { }

Query feature status

  • URL: /api/v1/feature/<FEATURE-UID>
  • Method: GET
  • Headers: { Connection-Uid: <CONNECTION-UID> }
  • Response: { "active": [true/false] }
  • Only applies to features implementing a certain mode such as ScreenLock. All features implementing simple actions will never be reported as active.

Available features

Name UUID
ScreenLock ccb535a2-1d24-4cc1-a709-8b47d2b2ac79
InputDevicesLock (Veyon >= 4.5.0) e4a77879-e544-4fec-bc18-e534f33b934c
UserLogoff 7311d43d-ab53-439e-a03a-8cb25f7ed526
Reboot 4f7d98f0-395a-4fff-b968-e49b8d0f748c
PowerDown 6f5a27a0-0e2f-496e-afcc-7aae62eede10

User information

  • URL: /api/v1/user
  • Method: GET
  • Response: { "login": "<USER-LOGIN-NAME>", "fullname", "<FULL-NAME-OF-USER>", "session": <DESKTOP-SESSION-ID> }
  • If no user is logged on, the login and fullname fields are empty and session is set to -1