DCImanager 6
en En
es Es
Your feedback is an opportunity for improvement!
Take part in the survey and contribute to the development of the ISPsystem ecosystem.
Take the survey

API guide

General information

API URL

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

Where

HTTP-request methods 

DCImanager 6 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
{
  "error":
  {
    "code": <error internal code, int>,
    "msg": <error message, string>,
    "value": <additional information, object>
  }
}

How to process code 503

If the platform service is inactive for a long time, it can be suspended. In this case, API requests are terminated with the code 503. Repeat the requests until another code is received in response:

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 6 session
SESSION6 = "6BA7C69DCB7DF4DACFFC7E56"


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(
        total=retries,
        read=retries,
        connect=retries,
        method_whitelist=['POST', 'GET', 'DELETE'],
        backoff_factor=0.01,
        status_forcelist=[503]
    )


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(
    'https://127.0.0.1/api/dci/v3/server/2',
    headers={HEADER_XSRT_TOKEN: SESSION6, HEADER_BOX: 'true'},
    cookies={COOKIE_SES6: SESSION6},
    verify=False
)
res.raise_for_status()
print(res.json())

Authorization methods 

There are three levels of API functions: 

  • public functions — they can be called without authorization;
  • 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 6 tries to find the x-xsrf-token parameter and the ses6 cookie-file in the HTTP-heading. They must contain the authorization token for the current user session. To receive the token, use the login/password or key authorization. 

Note
If you are running the request locally on the server with the platform, add an HTTP header to the request with the value isp-box-instance: true.

Login and password authorization

  1. Send the POST-request to the URL like https://domain.com/auth/v4/public/token.

    Request body in JSON
    {
      "email": "admin@example.com",
      "password": "secret"
    }
    Comments
    Usage in curl
    curl -X POST 'https://domain.com/api/auth/v4/public/token' -d '{"email": "admin@example.com", "password": "secret"}'
  2. Handle the response. It may contain error messages or JSON like this: 

    Response in JSON
    {
      "confirmed":true, 
      "id":"24",
      "token":"24-cee181d2-ccaa-4b64-a229-234aa7a25db6"
    }
    Comments
  3. Use the token that you have received in the heading of the HTTP request. E.g.: 

    Usage in curl
    curl -X POST 'https://domain.com/api/dci/v3/setting/operation_change_boot_order' -H 'Cookie: ses6=24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true' -d '{"value": "true"}'
  4. In the case of error you will receive the following message: 

    Authorization error
    {
      "error":
      {
        "code": 3001,
        "msg":"Unauthorized"
      }
    }

If the authorization token has not been used within 60 minutes, it will be deleted. To get a token with the desired lifetime, send the POST-request to a URL like https://domain.com/auth/v4/token

Request body in JSON
{
"expires_at": <time>,
"description": <comment>
}
Пояснения

The response will contain a new token with a specified expiration date.

Usage in curl
curl -X POST 'https://domain.com/auth/v4/token' -d '{"expires_at": "2030-01-31 00:00:00", "description": "Token for integration"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'

Changing token and session lifetime

By default, the token and session lifetime is 60 minutes. To change this setting, send a POST request to a URL like  https://domain.com/auth/v4/setting/token_ttl:

Request body in JSON
{
"value": "<time>"
}
Comments
Usage in curl
curl -X POST 'https://domain.com/auth/v4/setting/token_ttl' -d '{"value": "999"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a' -H 'Cookie:ses6=4-e9726dd9-61d9-2940-add3-914851d2cb8a'

Key authorization

DCImanager 6 supports throughout user authorization with admin login and password. Eg. it can be used to redirect authorized users from a billing system to DCImanager 6 or to provide temporary access to the platform for a user. The duration of this key is one hour.

  1. Send the POST-request to the URL like https://domain.com/auth/v4/public/token.

    Request body in JSON
    {
      "email": "admin@example.com",
      "password": "secret"
    }
    Comments
    Usage in curl
    curl -X POST 'https://domain.com/api/auth/v4/public/token' -d '{"email": "admin@example.com", "password": "secret"}'
  2. Handle the response. It may contain error messages or JSON like this: 

    Response in JSON
    {
      "confirmed":true, 
      "id":"24",
      "token":"24-cee181d2-ccaa-4b64-a229-234aa7a25db6"
    }
    Comments
  3. Send a POST-request to create the key:

    Create the authentication key
    curl -X POST 'https://domain.com/api/auth/v4/user/client@example.com/key'  -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true'  -d '{}'
    Comments

    You will receive a JSON-object like this: 

    Response in JSON
    {
      "id":"4",
      "key":"4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"
    }
    Comments
    Note

    With this key you can give the user temporary access to the platform. The user will be able to log in to the platform via a link in the following format: https://domain.com/auth/key-v4/<key>

    Comments
  4. To get the value of a token using a temporary key, send a POST request: 

    Receive the session number by the key
    curl -k -X POST 'https://domain.com/api/auth/v4/public/key' -H "isp-box-instance: true" -d '{"key": "4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"}'

    You will receive the JSON-object like this: 

    Response in JSON
    {
      "confirmed":true,
      "id":"123",
      "token":"1996-0082f9c6-0b07-43ca-b4e7-449c6b0df71f"
    }
    Comments
  5. Use the token that you have received in the heading of the HTTP request. E.g.:  

    Usage in curl
    curl -X POST 'https://domain.com/api/dci/v3/setting/operation_change_boot_order' -H 'Cookie: ses6=24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true' -d '{"value": "true"}'

    In the case of error you will receive the following message: 

    Authorization error
    {
      "error":
      {
        "code": 3001,
        "msg":"Unauthorized"
      }
    }


Related topics

The article was last updated on 06.14.2023. The article was prepared by technical writers of ISPsystem.