You interact with Plesk via REST API by sending API requests in the form of HTTP requests. REST API is based on OpenAPI Specification 2.0 (formerly Swagger Specification).

Only the Plesk administrator can use REST API.

There are various tools for working with API requests:

• API clients, software with a graphical interface for sending and receiving API requests, for example Postman.
• Command line tools such as curl.
• Swagger tools.

Regardless of the tool you choose, a typical API request consists of the following components:

• HTTP method
• URL
• Data type
• Transferred data
• Authorization methods

Let’s look closely at each one of them.

1 HTTP method

Depending on the action you want to perform, you use various HTTP methods in requests:

The data specified in the request determines what response you get back. Usually, the response contains a body with the information you have requested and an HTTP status code. The HTTP status code indicates if the request was successful or not. In general, if you receive a 2xx status code, the request was successful. Both 4xx and 5xx status codes mean that there has been an error processing your request. 4xx status codes tell you that the error is on your side (for example, bad syntax of the request), while 5xx status codes mean that the error is on the server’s side.

To choose which HTTP method to use, see the REST API autogenerated reference. Log in to Plesk and go to Tools & Settings > Remote API (REST), and then click API Reference and Playground (you will need to provide the server root or administrator user credentials).

2 URL

To communicate with Plesk via REST API, you need to send your API requests to a specific URL. The URL looks like this:

https://<hostname or IP address>:8443/api/v2/<API endpoint>

The API endpoint varies depending on the Plesk object you want to interact with. For example, the API endpoint for Plesk users is /clients.

To see the REST API description, access the following URL:

https://<hostname or IP address>:8443/api/v2/swagger.yml

You can use this URL to generate the API reference.

To learn which API endpoint you need to use, see the REST API autogenerated reference. Log in to Plesk and go to Tools & Settings > Remote API (REST), and then click API Reference and Playground (you will need to provide the server root or administrator user credentials).

3 Data Type

Information you send in requests and receive in responses has the form of JSON objects. In each API request, you must declare the content type you transfer in a request and expect in a response via the HTTP headers:

Content-Type: application/json

Accept: application/json

4 Transferred Data

With certain API requests, you need to send data in the JSON format inside the request body. For example, to create a customer, you need to post the following request body:

{
  "name": "John Doe",
  "login": "john_doe",
  "password": "password",
  "email": "john@doe.com",
  "company": "Plesk",
  "type": "customer"
}

To see examples of data required by each API request, see the REST API autogenerated reference. Log in to Plesk and go to Tools & Settings > Remote API (REST), and then click API Reference and Playground (you will need to provide the server root or administrator user credentials).

5 Authentication Methods

Each REST API request must be authenticated and sent via HTTPS. To authenticate requests, you need to use either basic authentication or API keys. We recommend that you choose API keys because they are more secure.

Basic Authentication

For basic authentication, you need to provide the credentials of one of the following users:

• The Plesk administrator.
• (Plesk for Linux) The root user.
• (Plesk for Windows) The administrator user

You can do it by adding the Authorization HTTP header that contains the word  Basic followed by a whitespace character and a base64-encoded string  username:password, for example:

Authorization: Basic YWRtaW46c2V0dXA=

Alternatively, if you use curl, you can specify the credentials via the --user or -u option, for example:

--user root:password

API keys

To create an API key, send the POST request with an empty request body {} to the following URL:

https://<hostname or IP address>:8443/api/v2/auth/keys

Note that you need to use basic authentication in the request above to create an API key.

Optionally, while creating an API key, you can provide the following parameters in the request body:

For example, to create an API key, you can send the request with the following body:

{
  "login": "administrator",
  "ip": "212.192.122.46",
  "description": "Secret Key"
}

When you have created an API key, pass it with each request instead of basic authentication. To do so, add the X-API-Key: key header:

X-API-Key: 78711059-23bb-cf6f-b07f-985e1995d2e2

Alternatively, you can create an API key using the secret_key utility, for example:

plesk bin secret_key -c -ip-address 10.58.108.104

In the output, you receive the key:

4897e11f-d053-0f83-1ac0-38b3822cfba8

Learn more about the secret_key utility on Linux and Windows.

6 Examples

Let’s see how to use REST API on practical examples using the curl command. The IP address of our Plesk server is https://10.58.108.104.

First, we create an API key to use it later for authentication:

curl -X POST --user root:password -H "Content-Type: application/json" -H "Accept: application/json" -d'{}' "https://10.58.108.104:8443/api/v2/auth/keys"

The key was created:

{"key":"5c6f1a8a-1263-7444-24e5-fcfd7b4dcdc6"}

Now we will use this API key to authenticate all following requests. Let’s get a list of all domains hosted on the server:

curl -X GET -H "X-API-Key: 5c6f1a8a-1263-7444-24e5-fcfd7b4dcdc6" -H "Content-Type: application/json" -H "Accept: application/json" "https://10.58.108.104:8443/api/v2/domains"

Then, we add a new customer:

curl -X POST "X-API-Key: 5c6f1a8a-1263-7444-24e5-fcfd7b4dcdc6" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"name":"John Doe","login":"john_doe","password":"password","email":"john@doe.com","type":"customer","company":"Plesk"}'  "https://10.58.108.105:8443/api/v2/clients"

The customer was added:

{"id":2,"guid":"9d4eb47b-817e-4c6b-b0ee-f2b7691986df"}

Configuring the REST API properties via panel.ini

Restricting Remote Access via REST API

Allowing HTTP

By default, REST API allows only HTTPS requests. HTTPS encrypts and secures the data sent via REST API. However, you can configure REST API to accept requests sent via plain HTTP. To do so, add the following lines to the panel.ini file:

[api]
allowPlainHttpAccess = on

Disabling or limiting CORS

By default, REST API allows cross-origin resource sharing (CORS). To enhance security, you can completely disable CORS or restrict it to particular domains and HTTP methods. To disable CORS, add the following lines to the panel.ini file:

[ext-rest-api]
cors.enabled = off

If you do not want to completely disable CORS, you can restrict its usage to particular domains and methods. To do so, add lines of the following pattern to the panel.ini file:

[ext-rest-api]
cors.origin = domain_name
cors.methods = HTTP_method

For example, to accept cross-origin API requests only with the GET and POST methods and only from example.com, add the following lines to panel.ini:

[ext-rest-api]
cors.origin = example.com
cors.methods = GET,POST