CloudStack API Guide

Overview

The Apache CloudStack API allows programmatic access to manage resources such as virtual machines, templates, networks, and more.
All API requests must include your API key and a signature.

This guide explains how to authenticate, generate a signature, and make a request using Postman with deployVirtualMachine as an example.

---

Prerequisites

Before starting, make sure you have:

• CloudStack API endpoint, e.g., https://studentcloud.ikdoeict.be/client/api
• Your API Key
• Your Secret Key
• The required parameters for your VM deployment

---

Authentication & Command Parameters

Parameter	Required	Description
apikey	✅	Your CloudStack API key for authentication
signature	✅	The HMAC-SHA1 signature generated using your secret key
command	✅	API command to execute; here deployVirtualMachine
response	⚙️ Optional	Response format (json or xml)

Source: Developers Guide

---

VM Deployment Parameters for deployVirtualMachine

Parameter	Required	Description
serviceofferingid	✅	Defines the VM CPU, RAM, and disk configuration
templateid	✅	The template ID for the VM image
zoneid	✅	The availability zone where the VM will run
name	⚙️ Optional	The name of the VM
networkids	⚙️ Optional	The network(s) to attach the VM to
domainid	⚙️ Optional	The domain ID for the VM
startvm	⚙️ Optional	Automatically start the VM after deployment
keyboard	⚙️ Optional	Keyboard layout (e.g., fr-be)

Source: Apache CloudStack API Documentation – deployVirtualMachine

---

1. Generating the Signature

To authenticate your request, you must generate an HMAC-SHA1 signature. Follow these steps:

1. Include all API parameters
   Include every parameter required for your API call except signature.

2. Sort parameters alphabetically
   Sort parameter names in case-insensitive alphabetical order.

3. URL-encode parameter values
   Encode values according to RFC 3986:

   • Spaces must be %20 (not +)
   • Reserved characters such as /, :, ?, &, = must be percent-encoded.

4. Concatenate as a query string Combine parameters into param1=value1&param2=value2&... using lowercase names and lowercase values, and URL-encode both names and values.

5. Compute HMAC-SHA1 hash
   Use your Secret Key as the HMAC key and hash the concatenated string with SHA1.

6. Base64-encode the hash
   Convert the HMAC-SHA1 digest into a Base64 string.

7. URL-encode the Base64 signature
   Encode the Base64 string for safe inclusion in the URL.

8. Include signature in your request
   Add the encoded signature as the signature parameter in your final API request.

---

Python Script for Generating Signature

The following Python script automates the generation of the HMAC-SHA1 signature required for CloudStack API requests.
Replace the placeholders with your Secret Key and API Key, then run the script to get the URL-encoded signature.

import hmac, hashlib, base64, urllib.parse

SECRET_KEY = ""   # <-- put your secret key here
params = {
    "apikey": "", # <-- put your API key here
    "command": "deployVirtualMachine",
    "domainid": "adb0dde2-11fd-4138-9c39-a9d42e1fc8d4",
    "keyboard": "fr-be",
    "name": "API-generated",
    "networkids": "dcee468a-13cb-433e-af51-535bd9517080",
    "serviceofferingid": "beefbcb6-ca1a-4501-a35c-e4fab1f26e05",
    "startvm": "true",
    "templateid": "cb2b3fa4-0d15-4547-987e-3bddd9a14af4",
    "zoneid": "52d98511-089b-4911-8e5a-126260da51ff",
    "response": "json"
}

# 1) Sort keys
pairs = []
for k in sorted(params.keys(), key=lambda s: s.lower()):
    val = urllib.parse.quote(params[k], safe='~')  # URL-encode value
    pairs.append(f"{k.lower()}={val}")

# 2) Build string to sign and lowercase it
string_to_sign = "&".join(pairs).lower()

# 3) HMAC-SHA1 and base64
digest = hmac.new(SECRET_KEY.encode('utf-8'),
                  string_to_sign.encode('utf-8'),
                  hashlib.sha1).digest()
signature = base64.b64encode(digest).decode('utf-8')

# 4) URL-encode the base64 signature
signature_encoded = urllib.parse.quote(signature, safe='')

print("String to sign:")
print(string_to_sign)
print()
print("Signature (paste this into Postman signature param):")
print(signature_encoded)