DCImanager Administrator

API guide


General information


Access the API by the URL https://domain.com/api/service/api_version/function/

domain.com — public IP address or the domain of the server with DCImanager

service — internal service for processing requests:

  • auth — authorization service;
  • dci — DCImanager API — the main service of the platform;
  • eservice — Equipment service — equipment management service;
  • ipmiproxy — IPMI Proxy service — proxy service for IPMI connections;
  • ip — IPmanager 6 — IP addresses, pools and networks management service

api_version — current version API: v3

function — function to be executed in DCImanager

HTTP-request methods 

DCImanager supports GET, POST, and DELETE.

POST-request methods 

To send parameters for a POST-request, specify them in the request body in a JSON format. 

Response format

A response to API-requests is sent in the form of JSON-objects, e.g.:

Error notification in JSON
    "code": <error internal code, int>,
    "msg": <error message, string>,
    "value": <additional information, object>

How to process code 503

DCImanager can be suspended if it is not active for a long time. API-requests will be terminated with the code 503. Send the requests again until you receive another code: 

Example on Python 3
def retry(fn, **kwargs):
    response = fn(**kwargs)
    if response.status_code == 503:
        for attempt in range(1, 11):
            time.sleep(0.1 * attempt)
            logging.info(f'Try connect to {kwargs["url"]} number {attempt}')
            response = fn(**kwargs)
            if response.status_code != 503:
    return response

def internal_post(url, data):
    headers = {"Host": "instance-" + os.environ["INSTANCE_ID"], "internal-auth": "on"}
    logging.info(f'Try connect to {url} with headers {headers}')
    retry(requests.post, url=url, json=data, headers=headers)
Example on Python 3
from urllib3.util.retry import Retry
from requests import Session
from requests.adapters import HTTPAdapter

HEADER_XSRT_TOKEN = "x-xsrf-token"
HEADER_BOX = "isp-box-instance"
COOKIE_SES6 = "ses6"
# specify id of DCImanager session

def _make_retry_object():
    Create an object to retry the API:
    total - number of attempts
    backoff_factor - affects the delay between requests
    method_whitelist - a list of methods for which request are repeated
    status_forcelist - list of statuses for which we request are repeated
  	retries and backoff_factor are selected so that the request does not hang
    for too long
    retries = 10
    return Retry(
        method_whitelist=['POST', 'GET', 'DELETE'],

def _make_session():
    Create a request.Session object to retry requests
    session = Session()
    session.verify = False
    session.mount("http", HTTPAdapter(max_retries=_make_retry_object()))
    session.mount("https", HTTPAdapter(max_retries=_make_retry_object()))
    return session

sess = _make_session()
res = sess.get(
    headers={HEADER_XSRT_TOKEN: SESSION6, HEADER_BOX: 'true'},
    cookies={COOKIE_SES6: SESSION6},

Authentication methods 

There are three levels of API functions: 

  • public functions — they can be called without authentication;
  • user functions — a user with the "User" access permissions can call the functions;
  • administrator functions — a user with the "Admin" access permissions can call the functions;

In order to check the user level, DCImanager tries to find the ses6 cookie-file in the HTTP-heading. It should contain the id of the current sessions of the user. To receive the session id, use the login/password or key authentication. 

Login and password authentication

  1. To receive a session number, send the POST-request to the URL like https://domain.com/auth/v3/auth

    Request body in JSON
      "email": your_email,
      "password": your_password
  2. Handle the response. It may contain error messages or JSON like this: 

    Response in JSON
      "expires_at": string,
      "id": int,
      "session": string
  3. Use the session number that you have received in the heading of the HTTP request. E.g.: 

    Usage in curl
    curl -k -H "Cookie:ses6=F2BABF12426B297C86FC5628" 'https://domain.com/api/auth/v3/user_exist/client@example.com'


    For POST and DELETE requests, additionally specify the session number in the -H 'x-xsrf-token: <ses6>' parameter. E.g.:

    Power on the server
    curl -X POST 'https://domain.com/api/dci/v3/server/server_id/power_on' -H 'Cookie: ses6=F2BABF12426B297C86FC5628' -H 'x-xsrf-token: F2BABF12426B297C86FC5628' -H 'isp-box-instance: true' -d '{}'| jq
  4. In the case of error you will receive the following message: 

    Authorization error
        "code": 1114,
        "msg": "Whoami verifired error",
          "code": 3002,
          "msg": "Session not found"

Key authentication 

DCImanager supports throughout user authentication with admin login and password. Eg. it can be used to redirect authorized users from BILLmanager to DCImanager.

How it works:

  1. Send a POST-request to create the key. You must have admin permissions to perform this operation:

    Create the authentication key
    curl -X POST 'https://domain.com/api/auth/v3/user/client@example.com/key' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{}'| jq
  2. You will receive a JSON-object like this: 

    Response in JSON
      "expires_at": "2019-12-21 23:59:59",
      "key": "94DA5B99AF0BF26D2E96458CABA8DA96"
  3. To get the session number, send the POST-request with the key that you have received: 

    Receive the session number by the key
    curl -X POST 'https://domain.com/api/auth/v3/auth_by_key' -d '{"key": "94DA5B99AF0BF26D2E96458CABA8DA96"}'| jq
  4. You will receive the JSON-object like this: 

    Response in JSON
      "expires_at": "2019-12-21 23:59:59",
      "id": 2,
      "session": "CC033C4629BAEF3852CFE27A"

Current session management

Receive information about the current session

  1. Send a GET-request with the number of the current session: 

    Receive informaion about the current session
    curl -X GET 'https://domain.com/api/auth/v3/whoami' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. You will receive the JSON-object like this:

    Response in JSON
      "expires_at": "2019-12-21 23:59:59",
      "lang": "ru",
      "owner_email": "client@example.com",
      "owner_id": 2,
      "roles": [
      "ses_id": 2,
      "session": "CC033C4629BAEF3852CFE27A",
      "trustee_email": "client@example.com",
      "trustee_id": 2

Terminate the session 

We recommend terminating a user session after you have completed your API operations: 

  1. Send a DELETE-request with the session number: 

    Close the session
    curl -X DELETE 'https://domain.com/api/auth/v3/session/CC033C4629BAEF3852CFE27A' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. You will receive a JSON-object like this:

    Response in JSON
      "status": "ok"
  3. When trying to use the session that has been already deleted you will receive a JSON-object like the following: 

    Session not found
      "error": {
        "code": 3002,
        "msg": "Session not found"
Thank you for your feedback!
Was the article useful?
Tell us why not:

it does not match the title

it was hard to understand

I didn't find the answer

recommendations from the article did not help


Tell us what you didn't like in the article: