About REST API
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:
Method | Usage |
---|---|
GET | Retrieves information about the object. Requests using the GET method are read-only and will not affect any of the queried objects. |
DELETE | Removes the object from the Plesk server. |
PUT | Updates the information about the object. |
POST | Creates a new object. |
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, go to Tools & Settings > Remote API (REST) (under “Server Management”),
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:
Parameter | Description | Type |
---|---|---|
login |
The login of a Plesk user who will have the secret key. If the parameter is not specified, the Plesk administrator’s login is used. | string |
ip |
The IP address that will be linked to an API key. If the parameter is not specified, the IP address of the sender will be used. | string |
description |
(Optional) Additional information about an API key. | string |
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
Note: The REST API does not allow passing API keys in URL arguments.
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
.
Note: If Plesk is secured with a self-signed or invalid SSL/TLS
certificate, use the -k
or -insecure
options with the
curl
command to allow insecure SSL connections.
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
Note: For security reasons, we do not recommend sending REST API requests via HTTP.
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