Zergaw Cloud Docs

API Keys

Zergaw CloudStack provides robust API authentication mechanisms, enabling secure and programmatic interaction with its extensive set of cloud services. This is crucial for automation, integration with custom applications, and managing your cloud infrastructure at scale.

Using API Key and Secret Key based Authentication

The primary method for programmatic access to Zergaw CloudStack APIs is through API Key and Secret Key-based Authentication. This mechanism is designed for secure, non-interactive use by scripts, applications, and automation tools.

How it Works:

  1. API Key (Access Key):

    • The API Key is a unique identifier generated by a user within Zergaw CloudStack.
    • It serves to uniquely identify the Account (and implicitly, the user associated with generating the key) making the API request.
    • The API Key is included directly in every API request as a parameter.
    • Visibility: While unique, the API Key itself is not considered highly sensitive on its own as it merely identifies the caller. Its security relies heavily on the Secret Key it's paired with.

  2. Secret Key (Secret Access Key):

    • The Secret Key is a cryptographic key also generated by the user, paired with a specific API Key.
    • Unlike the API Key, the Secret Key is highly sensitive and must be kept absolutely confidential. It is never transmitted directly in an API request.
    • Its sole purpose is to generate a secure digital signature for each API call. This signature proves the authenticity of the request, demonstrating that it was indeed made by the legitimate holder of the Secret Key.

  3. Signature Generation:

    • Before an API call is sent, a unique signature is computed. This signature is generated by performing a cryptographic hash (e.g., HMAC-SHA1) using the Secret Key on a standardized string derived from the API command and all its parameters.
    • This process ensures that even if an API request is intercepted, it cannot be tampered with or replayed without the correct Secret Key.

  4. API Request Structure:

    • When making an API call, the request (typically an HTTP GET or POST) includes:
      • The command (e.g., listVirtualMachines).
      • All necessary parameters for the command (e.g., zoneid=xyz, state=Running).
      • The API Key (apikey=YOUR_API_KEY).
      • The generated signature (signature=YOUR_GENERATED_SIGNATURE).
      • Additional parameters like response=json for desired output format.

  5. Authentication and Authorization by Zergaw CloudStack:

    • Upon receiving an API request, Zergaw CloudStack uses the provided API Key to retrieve the associated Secret Key stored on its side.
    • It then re-computes the signature using the received command and parameters with its stored Secret Key.
    • If the re-computed signature matches the signature provided in the request, the request is authenticated as legitimate.
    • After authentication, Zergaw CloudStack performs authorization checks to ensure that the user associated with the API Key has the necessary permissions to execute the requested command.

Benefits:

Managing API Keys:

Users can generate, view, and revoke API Keys and their associated Secret Keys through the Zergaw CloudStack UI found under the "Accounts > Select Account > View Users > Select User > Generate New API/Secret Keys(action button at the top). It is critical to:

Using API Keys to interact with Zergaw CloudStack

Getting Started

To get started using the API, you should have the following:

Making API Requests

All API requests are submitted in the form of a HTTP GET/POST with an associated command and any parameters. A request is composed of the following whether in HTTP or HTTPS:

A sample API GET request looks like the following:

https://cloudstack.zergaw.com/client/api
?command=deployVirtualMachine
&serviceOfferingId=1
&diskOfferingId=1
&templateId=2
&zoneId=4
&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Signing and executing a request

import hashlib, hmac, base64, urllib.parse, requests

endpoint = 'https://cloudstack.zergaw.com/client/api'
api_key = 'YyxQnLs4ZRi8szDafiUhCFR1Bvs-5t2XCo6gxGFi2NlZgskCHh4YGTQ20rGhD6TIDgVxLbBQbgTkQKbL32_emA'
secret = 'csvtt1l5OTD6qLStRID-2vMh-vXsKtSLab5wMv_F_2KaPdxG98Y-ofNfOeang7M6cxYcqBpNcU3fyI6sk8rtFg'

parameters (example: listUsers)

params = {
    'command': 'listUsers',
    'response': 'json',
    'apiKey': api_key
}
  1. create canonicalized query string (lowercase keys, sort)
sorted_items = sorted((k.lower(), params[k]) for k in params)
  1. URL encode values using urllib.parse.quote_plus
query = '&'.join(f"{k}={urllib.parse.quote_plus(str(v))}" for k, v in sorted_items)
  1. signature: HMAC-SHA1 of the lowercase query string (some docs require lowercasing)
sig = base64.b64encode(hmac.new(secret.encode('utf-8'),
                                query.lower().encode('utf-8'),
                                hashlib.sha1).digest()).decode()
sig = urllib.parse.quote_plus(sig)
  1. final URL
final = f"{endpoint}?{query}&signature={sig}"

r = requests.get(final, timeout=15, verify=True)
print(r.status_code, r.text)

Interacting with Zergaw CloudStack using python library

The easiest method of intracting with Zergaw CloudStack API is using the cs python library

pip install cs[async,highlight]

from cs import CloudStack

cs = CloudStack(endpoint='https://cloudstack.example.com/client/api',
                key='cloudstack api key',
                secret='cloudstack api secret')

print(cs.listVirtualMachines())