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) |
ProtocolMismatch | 12 | 501 (NotImplemented) |
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 belocalhost
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?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], "arguments": <ARGUMENTS> }
- Arguments are feature specific and described in the feature table below
- 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 | Arguments |
---|---|---|
ScreenLock | ccb535a2-1d24-4cc1-a709-8b47d2b2ac79 |
<none> |
InputDevicesLock (Veyon >= 4.5.0) | e4a77879-e544-4fec-bc18-e534f33b934c |
<none> |
UserLogoff | 7311d43d-ab53-439e-a03a-8cb25f7ed526 |
<none> |
Reboot | 4f7d98f0-395a-4fff-b968-e49b8d0f748c |
<none> |
PowerDown | 6f5a27a0-0e2f-496e-afcc-7aae62eede10 |
<none> |
DemoServer | e4b6e743-1f5b-491d-9364-e091086200f4 |
{ "demoAccessToken": <TOKEN> } |
FullScreenDemoClient | 7b6231bd-eb89-45d3-af32-f70663b2f878 |
{ "demoAccessToken": <TOKEN>, "demoServerHost": <DEMO-SERVER-HOST-ADDRESS> } |
WindowDemoClient | ae45c3db-dc2e-4204-ae8b-374cdab8c62c |
{ "demoAccessToken": <TOKEN>, "demoServerHost": <DEMO-SERVER-HOST-ADDRESS> } |
StartApp | da9ca56a-b2ad-4fff-8f8a-929b2927b442 |
{ "applications": ["<APP1-PATH-WITH-ARGUMENTS>", "<APP2-PATH-WITH-ARGUMENTS>", ...] } |
OpenWebsite | 8a11a75d-b3db-48b6-b9cb-f8422ddd5b0c |
{ "websiteUrls": ["<URL1>", "<URL2>", ...] } |
TextMessage | e75ae9c8-ac17-4d00-8f0d-019348346208 |
{ "text": "..." } |
- A demo token is an arbitrary ASCII string (e.g. base64-encoded random data) with a recommended length of at least 16 bytes
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
andfullName
fields are empty
Session information¶
- URL: /api/v1/session
- Method: GET
- Response:
{ "sessionId": <SESSION-ID>, "sessionUptime", <SESSION-UPTIME-IN-SECONDS>, "sessionClientAddress": "<ADDRESS-OF-SESSION-CLIENT>", "sessionClientName": "<SESSION-CLIENT-NAME>", "sessionHostName": "<NAME-OF-SESSION-HOST>" }
sessionId
- an integer representing the session ID assigned by the Veyon Service - to be used as offset to the server ports to access the corresponding session serversessionId
- the number of seconds that elapsed since the session has been opened (e.g. user logon time)sessionClientAddress
- the host/IP address of the client which is connected to the session (e.g. the host running an RDP client)sessionClientName
- the name the client which is connected to the session (e.g. the host running an RDP client)sessionHostName
- the name of the host on which the session is running, usually the local hostname
- Response: