Learn how to evaluate and integrate the VNC SDK
![We're here if you need help.](png/help-subhero.png)
VNC Cloud API¶
The VNC Cloud REST API enables you to obtain and manage cloud addresses in order to join devices to VNC Cloud and establish connections between them.
API summary¶
VNC Cloud API resources can be accessed by making HTTPS requests to their URI. All resource URIs have the following structure:
https://api.vnc.com/cloud/1.1/<resource>
Resource | Method | Call this to: |
---|---|---|
static-address |
POST | Obtain a new cloud address |
static-address |
GET | List all cloud addresses |
static-address/<cloud-address>/ready |
GET | Check whether a cloud address is ready to use |
static-address/<cloud-address> |
GET | Retrieve the details of a cloud address |
static-address/<cloud-address> |
PUT | Change the characteristics of a cloud address |
static-address/<cloud-address> |
POST | Reset a cloud address password |
static-address/<cloud-address> |
DELETE | Delete a cloud address |
Note that:
- All calls to resources are authenticated using your VNC Cloud API key and secret obtained from RealVNC, using the Basic Authentication scheme.
- Request bodies, where required, are represented by JSON-encoded objects, using the
application/json
content type. - Response bodies, where supplied, are represented by JSON-encoded objects, using the
application/json
content type. - There may be a short delay before a cloud address you’ve obtained or changed is ready to use.
Obtaining a new cloud address¶
A cloud address must have an action. The listen
action allows incoming connections. The connect
action allows outgoing connections. Typically, Viewers connect
and Servers listen
, although you can reverse this methodology if you wish.
A connect
cloud address can be a member of up to 16 groups. Bundling connect
cloud addresses into groups makes it easier to define which listen
cloud addresses they can connect to.
A listen
cloud address should explicitly specify the groups or individual connect
cloud address that can connect to it. It is permissible to omit an access control list, but note that every connect
cloud address obtained using the same VNC Cloud API key will be able to connect. You can nominate up to 24 groups and 8 individual connect
cloud addresses.
HTTP request¶
- Method
- POST
- URI
https://api.vnc.com/cloud/1.1/static-address
- Body
A JSON-encoded object with the following parameters:
Parameter Type Description allowedActions
Array of string Mandatory. Specify the action the cloud address performs. The value must be either connect
orlisten
.groups
Array of string Optional (though recommended) for a connect
cloud address. Specify a list of up to 16 groups the cloud address is a member of. Group names can be up to 256 UTF-8 characters. If omitted, the cloud address is not a member of any group.accessControl
Array of string Optional (though recommended) for a listen
cloud address. Specify thegroups
parameter in this object with a list of up to 24 groups that can connect. Specify thecloudAddresses
parameter in this object with a list of up to 8 individual cloud addresses that can connect. If omitted, every cloud address obtained using the same VNC Cloud API key can connect.- Since
- 1.0
- Usage examples
A
connect
cloud address:curl https://api.vnc.com/cloud/1.1/static-address -X POST -u <API-key>:<API-secret> -H "Content-Type:application/json" -H "Accept:application/json" -d '{ "allowedActions":["connect"], "groups":["developers","testers","marketing","sales"] }'
A
listen
cloud address:curl https://api.vnc.com/cloud/1.1/static-address -X POST -u <API-key>:<API-secret> -H "Content-Type:application/json" -H "Accept:application/json" -d '{ "allowedActions":["listen"], "accessControl": { "groups":["developers","sales"], "cloudAddresses":["ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRhAHCcvLXdEQogp"] } }'
HTTP response¶
- Body
A JSON-encoded object with the following parameters:
Parameter Type Description cloudAddress
string The identifier for the cloud address. cloudPassword
string The password for the cloud address. - Content example
{ "cloudAddress":"ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "cloudPassword":"Zdsf36E8Dy7XR7i4HlpK" }
HTTP status codes¶
A successful call returns 201 Created. An unsuccessful call returns either:
- 400 Bad Request
Note that particular bad requests additionally return a JSON-encoded object with
errorCode
set to one of the following codes, anderrorMessage
set to the associated description:Code Description 1001 The content type of the request body is something other than application/json
.1002 The content type your user agent is expecting for the response body is something other than application/json
.1003 You’ve specified an action that is not connect
orlisten
.1004 For a connect
cloud address, you’ve specified more than 16 groups. For alisten
cloud address, you’ve specified more than 24 groups or 8 individual cloud addresses.1005 You’ve created either an allowedActions
,groups
, orcloudAddresses
list, but not put anything in it.1006 A group name is either empty or longer than 256 characters. 1008 You’ve specified an access control list for a listen
cloud address, but not put any groups or individual cloud addresses in it.1009 Either you’ve specified an access control list for a connect
cloud address, or a group for alisten
cloud address. It should be the other way around.- 401 Unauthorized
- You’ve either not provided a VNC Cloud API key, or the one you have provided is not in our system.
- 403 Forbidden
- Your VNC Cloud API key is not well-formed.
- 404 Not Found
- 503 Service Unavailable
Listing your current cloud addresses¶
You can list all the cloud addresses you currently have available for use. This does not include cloud addresses previously obtained but deleted.
By default, up to 20 cloud addresses are returned on a page. If you have more than 20, the response has a Link
header containing a URI for the next page. If you want to change the number of cloud addresses returned per page, specify the limit
query parameter.
Note that if cloud addresses are added or deleted while paging, and a page already-viewed would be affected, you will have to call the API again to see the change. A page yet-to-be-viewed is updated, however.
HTTP request¶
- Method
- GET
- URI
https://api.vnc.com/cloud/1.1/static-address
Note the URI can accept the following query parameter:
Query parameter Description ?limit=<1-99>
The number of cloud addresses returned on each page. By default, this is 20. Specify a number between 1 and 99. - Since
- 1.1
- Usage example
curl https://api.vnc.com/cloud/1.1/static-address?limit=35 -X GET -u <API-key>:<API-secret> -H "Accept:application/json"
HTTP response¶
- Link
<url>; rel="next"
- Body
A JSON-encoded object with the following parameters:
Parameter Type Description cloudAddresses
Array of string A page containing up to limit
cloud addresses.- Content example
{ "cloudAddresses":[ "ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M" ] }
HTTP status codes¶
A successful call returns 200 OK if the current page has cloud addresses, and 204 No Content if you’ve reached the end of the list.
An unsuccessful call returns either:
- 400 Bad Request
Note that particular bad requests additionally return a JSON-encoded object with
errorCode
set to one of the following codes, anderrorMessage
set to the associated description:Code Description 1002 The content type your user agent is expecting for the response body is something other than application/json
.- 401 Unauthorized
- You’ve either not provided a VNC Cloud API key, or the one you have provided is not in our system.
- 403 Forbidden
- Your VNC Cloud API key is not well-formed.
- 404 Not Found
- 503 Service Unavailable
Checking whether a cloud address is ready to use¶
You may want to do this because there can be a slight delay before a cloud address you’ve obtained, changed or reset is ready to use.
HTTP request¶
- Method
- GET
- URI
https://api.vnc.com/cloud/1.1/static-address/<cloud-address>/ready
- Since
- 1.0
- Usage example
curl https://api.vnc.com/cloud/1.1/static-address/ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M/ready -X GET -u <API-key>:<API-secret> -H "Accept:application/json"
HTTP response¶
- Body
A JSON-encoded object with the following parameters:
Parameter Type Description changes
string The value is none
if the cloud address is ready to use, andpending
if it is not yet ready.- Content examples
If a cloud address is ready to use:
{ "changes":"none" }
If a cloud address is not yet ready:
{ "changes":"pending" }
HTTP status codes¶
A successful call returns 200 OK. An unsuccessful call returns either:
- 400 Bad Request
Note that particular bad requests additionally return a JSON-encoded object with
errorCode
set to one of the following codes, anderrorMessage
set to the associated description:Code Description 1002 The content type your user agent is expecting for the response body is something other than application/json
.1007 The cloud address you’ve specified in the URI is not well-formed. - 401 Unauthorized
- You’ve either not provided a VNC Cloud API key, or the one you have provided is not in our system.
- 403 Forbidden
- Your VNC Cloud API key is not well-formed.
- 404 Not Found
- 503 Service Unavailable
Retrieving the details of a cloud address¶
The response includes an ETag
header so you can subsequently check before you change, reset or delete the cloud address.
Note the response body does not include the cloud password. You must reset the password and generate a new one if you want to learn what it is.
HTTP request¶
- Method
- GET
- URI
https://api.vnc.com/cloud/1.1/static-address/<cloud-address>
- Since
- 1.0
- Usage example
curl https://api.vnc.com/cloud/1.1/static-address/ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M -X GET -u <API-key>:<API-secret> -H "Accept:application/json"
HTTP response¶
- ETag
<entity-version-number>
- Body
A JSON-encoded object with the following parameters:
Parameter Type Description cloudAddress
string The identifier for the cloud address. allowedActions
Array of string The action the cloud address performs. The value is either connect
orlisten
.groups
Array of string Optionally returned for a connect
cloud address only. Contains a list of groups the cloud address is a member of. If omitted, the cloud address is not a member of any group.accessControl
Object Optionally returned for a listen
cloud address only. May contain agroups
list with groups that can connect, and/or acloudAddresses
list with individual cloud addresses that can connect. If omitted, every cloud address obtained using the same VNC Cloud API key can connect.- Content examples
A
connect
cloud address:{ "cloudAddress":"ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "allowedActions":["connect"], "groups":["developer","testers","marketing","sales"] }
A
listen
cloud address:{ "cloudAddress":"ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "allowedActions":["listen"], "accessControl": { "groups":["developers","sales"], "cloudAddresses":["ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRhAHCcvLXdEQogp"] } }
HTTP status codes¶
A successful call returns 200 OK. An unsuccessful call returns either:
- 400 Bad Request
Note that particular bad requests additionally return a JSON-encoded object with
errorCode
set to one of the following codes, anderrorMessage
set to the associated description:Code Description 1002 The content type your user agent is expecting for the response body is something other than application/json
.1007 The cloud address you’ve specified in the URI is not well-formed. - 401 Unauthorized
- You’ve either not provided a VNC Cloud API key, or the one you have provided is not in our system.
- 403 Forbidden
- Your VNC Cloud API key is not well-formed.
- 404 Not Found
- 503 Service Unavailable
Changing the characteristics of a Cloud address¶
If you have previously retrieved this cloud address, you can use the If-Match
header to make sure it’s not been modified since.
Note you must send a fully-formed cloud address in the request body, including the actual cloud address itself. There is no concept of patching or appending to a cloud address.
HTTP request¶
- Method
- PUT
- URI
https://api.vnc.com/cloud/1.1/static-address/<cloud-address>
- Body
A JSON-encoded object with the following parameters:
Parameter Type Description cloudAddress
string Mandatory. Specify the identifier for the cloud address. This value must match the cloud address in the URI. allowedActions
Array of string Mandatory. Specify the action the cloud address performs. The value must be either connect
orlisten
.groups
Array of string Optional (though recommended) for a connect
cloud address. Specify a list of up to 16 groups the cloud address is a member of. Group names can be up to 256 UTF-8 characters. If omitted, the cloud address is not a member of any group.accessControl
Object Optional (though recommended) for a listen
cloud address. Specify thegroups
parameter in this object with a list of up to 24 groups that can connect. Specify thecloudAddresses
parameter in this object with a list of up to 8 individual cloud addresses that can connect. If omitted, every cloud address obtained using the same VNC Cloud API key can connect.- Since
- 1.0
- Usage examples
A
connect
cloud address:curl https://api.vnc.com/cloud/1.1/static-address/ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M -X PUT -u <API-key>:<API-secret> -H "Content-Type:application/json" -H 'If-Match:"<entity-version-number>"' -d '{ "cloudAddress":"ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "allowedActions":["connect"], "groups":["marketing","sales"] }'
A
listen
cloud address:curl https://api.vnc.com/cloud/1.1/static-address/ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M -X PUT -u <API-key>:<API-secret> -H "Content-Type:application/json" -H 'If-Match:"<entity-version-number>"' -d '{ "cloudAddress":"ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "allowedActions":["listen"], "accessControl": { "groups":["testers","marketing"], "cloudAddresses":["ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRhAHCcvLXdEQogp", "ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRPN9iZyuCdGaM7z"] } }'
HTTP response¶
There is no response body.
HTTP status codes¶
A successful call returns 200 OK. An unsuccessful call returns either:
- 400 Bad Request
Note that particular bad requests additionally return a JSON-encoded object with
errorCode
set to one of the following codes, anderrorMessage
set to the associated description:Code Description 1001 The content type of the request body is something other than application/json
.1003 You’ve specified an action that is not connect
orlisten
.1004 For a connect
cloud address, you’ve specified more than 16 groups. For alisten
cloud address, you’ve specified more than 24 groups or 8 individual cloud addresses.1005 You’ve created either an allowedActions
,groups
, orcloudAddresses
list, but not put anything in it.1006 A group name is either empty or longer than 256 characters. 1007 The cloud address you’ve specified in the URI is not well-formed. 1008 You’ve specified an access control list for a listen
cloud address, but not put any groups or individual cloud addresses in it.1009 Either you’ve specified an access control list for a connect
cloud address, or a group for alisten
cloud address. It should be the other way around.- 401 Unauthorized
- You’ve either not provided a VNC Cloud API key, or the one you have provided is not in our system.
- 403 Forbidden
- Your VNC Cloud API key is not well-formed.
- 404 Not Found
- 409 Conflict
- The
cloudAddress
you’ve specified in the request body may be well-formed, but it does not match the cloud address in the URI. - 412 Precondition Failed
- You’ve specified the
If-Match
header but the entity version numbers do not match. - 503 Service Unavailable
Resetting a cloud address password¶
If you have previously retrieved this cloud address, you can use the If-Match
header to make sure it’s not been modified since.
HTTP request¶
- Method
- POST
- URI
https://api.vnc.com/cloud/1.1/static-address/<cloud-address>
- Since
- 1.0
- Usage example
curl https://api.vnc.com/cloud/1.1/static-address/ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M -X POST -u <API-key>:<API-secret> -H 'If-Match:"<entity-version-number>"' -H "Accept:application/json"
HTTP response¶
- Body
A JSON-encoded object with the following parameters:
Parameter Type Description cloudAddress
string The identifier for the cloud address. cloudPassword
string The password for the cloud address. - Content example
{ "cloudAddress":"ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M", "cloudPassword":"RsBnHCoOoaiulwled71v" }
HTTP status codes¶
A successful call returns 200 OK. An unsuccessful call returns either:
- 400 Bad Request
Note that particular bad requests additionally return a JSON-encoded object with
errorCode
set to one of the following codes, anderrorMessage
set to the associated description:Code Description 1002 The content type your user agent is expecting for the response body is something other than application/json
.1007 The cloud address you’ve specified in the URI is not well-formed. - 401 Unauthorized
- You’ve either not provided a VNC Cloud API key, or the one you have provided is not in our system.
- 403 Forbidden
- Your VNC Cloud API key is not well-formed.
- 404 Not Found
- 412 Precondition Failed
- You’ve specified the
If-Match
header but the entity version numbers do not match. - 503 Service Unavailable
Deleting a cloud address¶
If you have previously retrieved this cloud address, you can use the If-Match
header to make sure it’s not been modified since.
HTTP request¶
- Method
- DELETE
- URI
https://api.vnc.com/cloud/1.1/static-address/<cloud-address>
- Since
- 1.0
- Usage example
curl https://api.vnc.com/cloud/1.1/static-address/ztgDAEjLLP4yHwHrdz9.ztgPXJMFsk1NiEGpbAx.livEXXxXXSrGS1urBF5.FCRPRHbrZPyfmS6Nt4M -X DELETE -u <API-key>:<API-secret> -H 'If-Match:"<entity-version-number>"'
HTTP response¶
There is no response body.
HTTP status codes¶
A successful call returns 204 No Content. An unsuccessful call returns either:
- 400 Bad Request
Particular bad requests return a JSON-encoded object with
errorCode
set to one of the following codes, anderrorMessage
set to the associated description:Code Description 1007 The cloud address you’ve specified in the URI is not well-formed. - 401 Unauthorized
- You’ve either not provided a VNC Cloud API key, or the one you have provided is not in our system.
- 403 Forbidden
- Your VNC Cloud API key is not well-formed.
- 404 Not Found
- 412 Precondition Failed
- You’ve specified the
If-Match
header but the entity version numbers do not match. - 503 Service Unavailable