Skip to main content

Public API

Abstract

Get basic information on GravityZone APIs and how to use them.

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

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 a specific number of requests per second per API key. If this limit is exceeded, subsequent requests are rejected and 429 HTTP status code is returned, along with a Retry-After header specifying the number of seconds left until you can send a new request.

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 the machine hostname, domain or IP where GravityZone is installed: https://YOUR-HOSTNAME/api/v1.0/jsonrpc/. To obtain the full URL of the API, add the API name to the base URL.

access_url.PNG

Currently, the following APIs are being exposed:

  1. Accounts, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/accounts
  2. Network, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/network
  3. Packages, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/packages
  4. Policies, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/policies
  5. Reports, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/reports
  6. Quarantine, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/quarantine
  7. General, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/general
  8. Sandbox, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/sandbox
  9. Sandbox Portal, with the API URL:

    https://SANDBOX-IP/api/v1
  10. Maintenance windows, with the API URL:

    https://YOUR-HOSTNAME/api/v1.0/jsonrpc/maintenanceWindows

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://YOUR-HOSTNAME/ using an administrator account. Your account must have the following rights: Manage Networks, Manage Users, Manage Company, and View and analyze data.

  2. Click your username in the upper right side of the console and select My Account:

    console_my_account_121716_en.png
  3. Go to the API keys section and click the Add button:

    console_my_account_add_API_key121716_en.png
  4. Type in a description for the key and select the APIs you want to enable for use with this key:

    console_my_account_configure_API_key_op_121716_en.png
  5. Click Generate.

    Note

    A window will be displayed with the newly generated API key and a warning stating that the key is only available for you to read while the window is open. After closing the window you will no longer be able to view the key anywhere in GravityZone.

    console_my_account_display_API_key_121716_en.png
  6. Click the copy_to_clipboard_121716_en.png button to copy the key to clipboard and save it in a safe location.

  7. Close the API key window.

The new key is added under the API keys section in an obfuscated format along with its description and creation date, and a list of enabled APIs.

console_my_account_add_API_key_result_121716_en.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!

Control Center also allows you to delete the previously generated API keys if they are no longer needed:

  1. Select the API key from the list.

  2. Click the Delete button:

    console_my_account_delete_API_key_121716_en.png
  3. Select Yes to confirm the deletion.

    Warning

    You will no longer be able to use the keys and any connections to third party apps using them will be terminated.

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).