CLOUD SOLUTIONS

Getting Started

Introduction

Bitdefender Control Center APIs allow developers to automate business workflows.

The APIs are exposed using JSON-RPC 2.0 protocol specified here:

http://www.jsonrpc.org/specification

Here is an example of API call updating the company name inside Control Center:

    {
        "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7",
        "jsonrpc": "2.0",
        "method": "updateCompanyDetails",
        "params": {
            "name": "My Company Name"
        }
    }    

For this call, the following response is sent back to the application:

    {
        "id":"91d6430d-bfd4-494f-8d4d-4947406d21a7",
        "jsonrpc":"2.0",
        "result": null
    }    

Each API call targets a method and passes a set of parameters.

There are two types of parameters:

  • required: MUST be always passed to the called method.

  • optional: has a default value and can be omitted from the parameters list. Any optional parameter can be skipped, regardless its position in the parameters list.

API requests

The API calls are performed as HTTP requests with JSON-RPC messages as payload. HTTP POST method MUST be used for each API call. Also, it is required that each HTTP request have the Content-Type header set to application/json.

Note

The API is limited to maximum 10 requests per second per API key. If this limit is exceeded, subsequent requests are rejected and 429 HTTP status code is returned.

Control Center exposes multiple APIs targeting distinct areas in the product. Each API exposes a set of methods related to a designated product area.

The base URL for all APIs is: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/. The full URL of the API is obtained by adding the API name to the base URL.

The CONTROL_CENTER_APIs_ACCESS_URL is displayed in the Access URL field. To find this field click your username in the upper-right corner of the console and choose My Account. Go to the Control Center API section.

access_url.PNG

Currently, the following APIs are being exposed:

  1. Companies, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/companies
  2. Licensing, with the API URL:

     CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/licensing
  3. Accounts, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/accounts
  4. Network, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/network
  5. Packages, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/packages
  6. Policies, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/policies
  7. Integrations, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/integrations
  8. Reports, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/reports
  9. Push, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/push
  10. Incidents, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/incidents
  11. Maintenance windows, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/maintenanceWindows
  12. Quarantine, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/quarantine
  13. General, with the API URL:

    CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/general

The HTTP requests containing JSON RPC 2.0 can be performed on each API URL in order to consume the exposed functionality.

Note

Batch requests and notifications are not currently supported by Control Center.

API Keys

The API key is a unique key that is generated in MyAccount section of Control Center. Each API key allows the application to call methods exposed by one or several APIs. The allowed APIs are selected at the time the API key is generated.

To generate API keys:

  1. Log in to https://gravityzone.bitdefender.com/ using your Control Center account.

  2. Click your username in the upper-right corner of the console and choose My Account.

  3. Go to the API keys section and click the Add button at the upper side of the table.

  4. Select the APIs that you want to use.

    api_keys.png
  5. Click Save. An API key will be generated for the selected APIs.

    api_keys_2.png

Important

By using the API keys, developers can access sensitive information such as packages and inventory. Please do not share or distribute your own generated API keys, in order to prevent the leaking of sensitive information!

Authentication

The API calls to Control Center are authenticated at HTTP protocol level using the HTTP Basic Authentication mechanism described here.

The client application is required to send the Authorization request header each time it performs a call to an API.

The Authorization header consists of the following elements:

  1. The authorization method and a space as the prefix; in our case, this will always be equal to Basic.

  2. A Base64 encoded string, generated from the combined username:password sequence.

    In our case, the API key is set as username, and password is set as an empty string.

    For example, if the API Key is equal to

    N8KzwcqVUxAI1RoPi5jyFJPkPlkDl9vF, the Base64 encoding should be performed on the following string:

    N8KzwcqVUxAI1RoPi5jyFJPkPlkDl9vF:. In this case, the content sent to the authorization header is

    Basic TjhLendjcVZVeEFJMVJvUGk1anlGSlBrUGxrRGw5dkY6.

Errors reporting

Control Center returns an error if the requested API method is unable to perform the desired task.

Here is an example of error response for a failing API call:

      {
          "id":"4d77e2d9-f760-4c8a-ba19-53728f868d98",
          "jsonrpc" : "2.0",
          "error" : {
              "code" : -32601,
              "message" : "Method not found",
              "data" : {
                  "details" : "The selected API is not available."
              }
          }
      }    

The error code and error message are returned as specified in JSON-RPC 2.0 Specification:

Error

Code

Message

Parse error

-32700

Parse error

Invalid Request

-32600

Invalid Request

Method not found

-32601

Method not found

Invalid params

-32602

Invalid params

Server error

-32000

Server error

The full description of the error is placed in data.details member in the error message.

Also, the HTTP status code is set according to the type of errors:

HTTP status

Description

401 Unauthorized

is set if the authentication failed for the request (e.g. the API key is incorrect or missing)

403 Forbidden

is set if the request is not authorized to consume the desired functionality (e.g. the API is not enabled for the used API key)

405 Method Not Allowed

the HTTP method is other than POST

429 Too Many Requests

more than 10 requests per second have been issued from the same IP address

200 HTTP status code

is returned for successful requests or for requests that have failed due to server errors (e.g. a required parameter is not passed).