Creating Session Tokens

The create_session operation is used to create a user session token, which can be used in single-use URLs for automatic logging in to Plesk. Using session tokens is a recommended, more secure way than passing login and plain password in URL.

For details about the one-time use URL, see Automatic Logging In to Plesk in Advanced Administration Guide for Linux or Advanced Administration Guide for Windows.

Request Packet Structure

A request contains the create_session operation node:

<packet>
  <server>
    <create_session>
      ...
    </create_session>
  </server>
</packet>

The create_session node is presented by the complex type CreateSessionType (server_input.xsd) and structured as follows:

• The login node is required. It specifies the login of the user for whom you create a session. Data type: string.
• The user-ip node is required. It specifies the IP address of the user that you specify in the login element. Data type: string.
• The c_email node is optional. It specifies the user's email address. If a user has no email in Plesk and this node is also not set, then the user will be prompted to enter the email address when opening the specified URL. The specified email is saved permanently in Plesk. Data type: string.
• The c_phone node is optional. It specifies the user's phone number. If a user has no phone number in Plesk and this node is also not set, then the user will be prompted to enter the phone number when opening the specified URL. The specified phone number is saved permanently in Plesk. Data type: string.
• The starting_url node is optional. It specifies the URL to which the user will be redirected within the Plesk UI. If not specified, the default URL will open. Data type: string.
• The source_server node is required. It specifies the URL from which the user came to Plesk. If specified, then after logging out from Plesk, the user will be redirected to this URL. Data type: string.
• The navigation node is optional. It specifies the navigation bar object that will replace the Plesk's navigation bar - that is the left frame menu in the Server Administration Panel (the Service Provider view). The navigation object is a Base64-encoded serialized array. Data type: string.

  One way to create a custom navigation menu is modifying the default Plesk's navigation menu. Use the get_navigation command of the ui operator in order to get the default Plesk's navigation menu in the form of encoded serialized array. After modification, use it in create_session requests.

• The pathbar node is optional. This parameter is not used.
• The logo_ing_url node is optional. It specifies the URL of the image to be used as a logo at the top of the screen. Data type: string.
• The logo_ing_ref node is optional. It specifies the URL of the page to which a click on the logo leads. Data type: string.
• The locale_id node is optional. It specifies the language code of the locale to be used in Plesk for the specified user, for example, en-US. The specified language code is saved permanently in Plesk in interface settings of this user. Data type: string.
• The skin node is optional. It specifies the name of the Plesk interface theme to be used for the specified user. Data type: string.
• The domain node is optional. It specifies the domain name that the specified user should access. Data type: string.
• The disable_lock_screen node is optional. It specifies whether a user will be able to work in Plesk while Plesk's UI screens are still loading. Possible values: true or false. Data type: string.
• The max_button_length node is optional. This parameter is not used.
• The back_url node is optional. It specifies the URL from which the user came to Plesk. If specified, then after logging out from Plesk, the user will be redirected to this URL. This node duplicates the source_server node. Data type: string.

Important: All values for session parameters (from user_ip to back_url) must be encoded using the Base64 algorithm.

If optional parameters are not specified in an XML API request, then Plesk uses default values. Otherwise, the values you set in a request will replace the default ones.

User's email address, phone number and preferred language will be stored in Plesk permanently for the specified user. Other parameters work only during a session.

The following request creates a session for the user admin:

<packet>
  <server>
    <create_session>
      <login>admin</login>
      <data>
        <user_ip>MTAuNTAuMS43MQ==</user_ip>
        <source_server></source_server>
      </data>
    </create_session>
  </server>
</packet>

The login parameter specifies the Plesk user for whom you want to create a session. The user-ip parameter is an IP address of the user, encoded using the Base64 algorithm.

Important: When creating request packets, put nodes and elements in the order they follow in the packet structure.

Response Packet Structure

The create_session node of the response packet is structured as follows:

• The result node is required. It wraps the result of the create_session operation. Data type: CreateSessionResultType (server_output.xsd).
• The status node is required. It returns the execution status of the operation. Data type: result_status. Allowed values: ok | error.
• The errcode node is required if the operation fails. Returns error code. Data type: unsignedInt.
• The errtext node is is required if the operation fails. Returns error message. Data type: string.
• The id node required. It returns a generated session token. Data type: string.

Samples

This request creates session tokens:

<packet>
  <server>
    <create_session>
      ...
    </create_session>
  </server>
</packet>

Response:

<packet>
  <server>
    <create_session>
      <result>
        <status>ok</status>
        <id>ede520d0fc93ae7aa0524076d631fba2</id>
      </result>
    </create_session>
 </server>
</packet>

Plesk creates a session token for the specified user. It is contained in the id tag (ede520d0fc93ae7aa0524076d631fba2 in the example).