Getting started with the OpenvCloud Cloud API

Swagger UI

The Swagger UI of the Cloud API is available both in the End User Portal, and the System Portal as shown in Cloud API.

In the End User Portal click the Machine API in the top menu bar:

From there you can, for instance, click cloudapi__cloudspaces which expands all available API end points related to cloud spaces:

Clicking the POST /cloudapi/cloudspaces/create expands a form that allows you to create a cloud space:

Here's an example with some valid values:

And here's the result when you hit Try it out!:

From the command line

Two options:



  • Registrated user on

  • OpenvCloud access rights for the user

In order to get a JWT from, you first need to create an application key for your identity:

Copy the created Application ID and Secret into environment variables:


Get the JWT from

JWT=$(curl -d 'grant_type=client_credentials&client_id='"$CLIENT_ID"'&client_secret='"$CLIENT_SECRET"'&response_type=id_token'

Get the accounts using the OpenvCloud Cloud API, passing the JWT in the header of the HTTPS request:

curl -X POST -H 'Authorization: bearer '"$JWT" $URL/restmachine/cloudapi/accounts/list

Username and password

Set the username and password:


First get a session key from the Openvcloud Cloud API:

SESSION_KEY=$(curl -X POST -d 'username='"$USER_NAME"'&password='"$PASSWORD" $URL/restmachine/cloudapi/users/authenticate)

List all cloud spaces using the OpenvcCoud Cloud API, passing the session key in the authkey query string:

curl -X POST $URL/restmachine/cloudapi/cloudspaces/list?authkey=$SESSION_KEY

Using python

Make sure you've exported your client ID and secret:

export CLIENT_ID

In the interactive shell:

import os
import requests
params = {
'grant_type': 'client_credentials',
'response_type': 'id_token',
'client_id': os.environ['CLIENT_ID'],
'client_secret': os.environ['CLIENT_SECRET'],
'validity': 3600
url = ''
resp =, params=params)
JWT = resp.content.decode('utf8')
headers = {'Authorization': 'bearer %s' % JWT}
url= ""
resp =, headers=headers)

Using Portal client

If portal code is installed it is possible to use the portal client directly to connect to the OVC API:

pcl = j.clients.portal.getByInstance('main')
# List cloudspaces

Calling the api asynchronously

Some API calls are long tasks and they can be blocking in certain cases. It is possible to call these functions asynchronously. This will return to the user the task guide of that call, which can then be polled to get the state of the job.

This is achieved by sending _async=True in the request body. An example using the second portal client which allows async calls:

pcl = j.clients.portal.getByInstance2("main")
task_guid = pcl.cloudapi.images.create(
report = pcl.system.task.get(taskguid=task_guid)
# Report will return None until the task is completed.
# When finishing it will return a pair of [Bool, result]. Bool signifies success or failure of that call.

Or by using curl:

curl -X POST -H "Authorization: bearer {token}" -d '_async=True'
# Will return {taskguid}
curl -X POST -H "Authorization: bearer {token}" -d 'taskguid={taskguid}'