To create a secret key, use the create operation.

Creating a secret key, you can specify the IP address and/or the login name of the Plesk customer or reseller the secret key will be assigned to. If you do not specify any IP address, Plesk will assign the secret key to the IP address of the request sender. Plesk XML API will deny requests that use the secret key but were sent from other IP addresses. If you do not specify any login name, Plesk will assign the secret key to the Plesk administrator.

Note: For security reasons, secret keys are shown only when they are created. Once you have created a secret key, copy it and and keep it safe. Plesk XML API will not show the secret key again.

Request Packet Structure

A request XML packet that creates secret keys includes the create operation node:

<packet>
    <secret_key>
        <create>
            ...
        </create>
    </secret_key>
</packet>

The create node has the following graphical representation:

image 75880

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.9.1/agent_input.svg.

  • The ip_address node is optional. It specifies the IP address that will be assigned to the secret key. If you do not specify this node, Plesk XML API will use the IP address of the request sender. Data type: ip_address (common.xsd).
  • The description node is optional. It specifies additional information about the secret key. Data type: string.
  • The login node is optional. It specifies the login name of the Plesk customer or reseller the secret key will be assigned to. The customer or reseller account must be active. If you do not specify this node, Plesk XML API will use the administrator login name. Data type: string.

Remarks

You can create multiple secret keys in a single request. To do so, add as many create operations as many secret keys you want to create.

<create>
   ...
</create>
   ...
<create>
   ...
</create>

Note: To create request packets, put the nodes and elements in the same order they appear in the request packet structure.

Response Packet Structure

The create node of the response XML packet is structured as follows:

image 37142

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.9.1/agent_output.svg.

  • The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd).
  • The status node is required. It specifies the execution status of the create operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. It returns an error code if the create operation fails. Data type: integer.
  • The errtext node is optional. It returns an error message if the create operation fails. Data type: string.
  • The key node is optional. It holds the secret key value if the operation succeeds. Data type: string.

Samples

Creating a Secret Key Assigned to the Specified IP Address

The following request creates a secret key for the IP address 192.0.2.1:

<packet>
    <secret_key>
        <create>
            <ip_address>192.0.2.1</ip_address>
        </create>
    </secret_key>
</packet>

Response:

<packet>
    <secret_key>
        <create>
            <result>
                <status>ok</status>
                <key>24f8c5e5-fcb5-bdfc-aac0-7bff0e800334</key>
            </result>
        </create>
    </secret_key>
</packet>

Creating a Secret Key Assigned to the Specified IP Address and Customer

The following request creates a secret key assigned to the IP address 192.0.2.1 and to the customer with the login name john_doe:

<packet>
    <secret_key>
        <create>
            <ip_address>192.0.2.1</ip_address>
            <login>john_doe</login>
        </create>
    </secret_key>
</packet>

Response:

<packet>
    <secret_key>
        <create>
            <result>
                <status>ok</status>
                <key>c5b239d1-8eb6-8cee-76b7-aa16be37fee8</key>
            </result>
        </create>
    </secret_key>
</packet>

Creating Multiple Secret Keys

The following request creates secret keys for the users with the login names user1 and user2:

<packet>
    <secret_key>
        <create>
            <login>user1</login>
        </create>
        <create>
            <login>user2</login>
        </create>
    </secret_key>
</packet>

Response:

<packet>
    <secret_key>
        <create>
            <result>
                <status>ok</status>
                <key>d0db111b-9736-6ae1-f92e-7d5f7eb34a72</key>
            </result>
        </create>
        <create>
            <result>
                <status>ok</status>
                <key>28698061-0b46-1d96-c0de-336cdbdb0fa5</key>
            </result>
        </create>
    </secret_key>
</packet>