The server/session REST API endpoint 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 a login and plain password in a URL.

Learn more about automatic logging in to Plesk

Note

Permissions for creating a session token via this endpoint vary by role:

  • Plesk administrator (main or additional) — can create session tokens for themselves, resellers, and customers.

  • Resellers — can create session tokens for themselves and their customers only.

  • Customers — can create session tokens for themselves only.

Additional permission requirements:

  • For an additional administrator account with restricted access, the Ability to use remote API permission must be enabled on Tools & Settings > Restricted Mode Settings > Administrative Tools.

  • For a reseller, the Ability to use remote API permission must be enabled on Service Plans > Reseller Plans > <reseller plan> > Permissions.

Note

The XML API’s create_session operation creates a session token the same way this endpoint does, but it doesn’t support skipping the MFA prompt for session-token logins. If you need that capability, use this REST API endpoint instead; see Skipping MFA for Session-Token Logins below.

Request

Send a POST request to the server/session endpoint:

POST https://<server-hostname-or-ip>:8443/api/v2/server/session

with the following request body:

{
  "login": "johndoe",
  "user_ip": "192.0.2.1",
  "skip_mfa": false
}

The request body accepts the following parameters:

Parameter

Required

Type

Description

login

Yes

string

The login of the Plesk user for whom you want to create a session.

user_ip

No

string

The IP address of the user who will use the session. If not specified, the IP address of the request sender is used.

Note

For this restriction to take effect, clear the Allow IP address changes during a single session check box on Tools & Settings > Session Idle Time.

skip_mfa

No

boolean

If set to true, the user is not asked for a multi-factor authentication (MFA) code the first time they log in with this session token. Default: false. See Skipping MFA for Session-Token Logins below.

Response

Status code

Meaning

201

Session was successfully created.

400

Invalid request data (see Error Response below).

401

Unauthorized.

403

Permission denied.

A successful (201) response returns the created session token:

{
  "id": "df9d386ee5ef13dbcd583c1f616857a2"
}

The id field contains the generated session token (df9d386ee5ef13dbcd583c1f616857a2 in the example). Use this value as the PLESKSESSID parameter in the single-use login URL, as described in Automatic Logging In to Plesk:

https://<server-hostname-or-ip>:8443/enterprise/rsession_init.php?PLESKSESSID=<session_token>&success_redirect_url=<success_redirect_url>&failure_redirect_url=<failure_redirect_url>

Error Response

A 400 response returns an error code and message, for example:

{
  "code": 400,
  "message": "Account with this name already exists"
}

Skipping MFA for Session-Token Logins

By default, if the Multi-Factor Authentication extension is enabled for a user, Plesk still asks that user for an MFA code the first time they use a session-token login link. If the session token was already obtained through a system that itself enforces MFA (for example, your own MFA-protected customer portal), this second prompt may be redundant for your integration.

To let a session token skip this MFA prompt:

  1. On the Plesk server, add the following section to the panel.ini file:

    [ext-mfa]
allowSkipRSession = true

    This setting is false by default, meaning skip_mfa has no effect even if it is sent in the request.

  2. When creating a session token, set "skip_mfa": true in the request body (see Request above).

Note

Enable allowSkipRSession only if you fully trust the system that creates the session tokens, because doing so lets that system bypass Plesk’s MFA prompt for the users it logs in this way through this endpoint. Regular panel logins with a login and password are not affected — MFA is still enforced for those, regardless of this setting.

Samples

This request creates a session token for the customer johndoe, skipping the MFA prompt:

POST https://192.0.2.1:8443/api/v2/server/session

{
  "login": "johndoe",
  "user_ip": "192.0.2.1",
  "skip_mfa": true
}

Response:

{
  "id": "ede520d0fc93ae7aa0524076d631fba2"
}

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