cPanel/Session
cPanel module

Session

4 functions, invoked through the cpanel_uapi tool.

scope cpanel:uapi
Call any function with cpanel_uapi(service_id, module="Session", function, params). Live availability depends on the cPanel features JetHost has enabled on your account — call list_cpanel_operations to see what is active.

create_temp_user GET#

Create user session with existing session

This function creates a temporary user session.

Important:

  • Because this function requires a valid cPanel session ID, you must call it via a cPanel or Webmail session URL. If you call this function via the command line or Template Toolkit, it will not create a temporary user session. You must use the WHM API 1 create_user_session function to create a temporary user session.
  • Third-party plugins that require access to temporary MySQL users must call this function via the URL. It will create the temporary users before they are available. You can find these users in the $ENV{'REMOTE_DBOWNER'} environment variable.
  • If you cannot update your system, update your scripts to call the Cgi::phpmyadminlink function. This will create a temporary user session for you.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

createdinteger
Whether the function successfully created the temporary user session. 1 - Success. 0 - Failure.
One of: 0 1
session_temp_userstring
The temporary user's session ID.

create_webmail_session_for_mail_user GET#

Create Webmail session

Create a temporary session for a cPanel user to connect to Webmail.

Note:

The cPanel user must own the Webmail account.

### How to use this API

After you successfully call this API, you will need to log in to Webmail. To do this, send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:

  • $URL_AUTHTY represents the value from the hostname return.
  • If the hostname return value is null, enter the hostname of the server that answered the API function.
  • $token represents the value from the token return.
  • $session represents the value of the session return.

For example, an HTTP POST may resemble the following:

``https://hostname.example.com:2096/cpsess2462418786/login``

With a message body of:

``session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137``

domainstringRequired
The domain for the Webmail account.
loginstringRequired
The Webmail account's username.
localestringOptional
The locale that the new session will use. Note: You must only enter lowercase characters. This parameter defaults to the cPanel user's locale.
remote_addressstringOptional
The session's client IP address. Note: If you run this function from the command line, this parameter is required. This parameter defaults to the API caller's IP address.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

hostnamestring
The Webmail server's hostname. Note: The function returns a null value when the Webmail server is not remote.
sessionstring
The session ID to submit via POST to begin using the new session.
tokenstring
A new security token.

create_webmail_session_for_mail_user_check_password GET#

Create Webmail session with credentials

This function creates a temporary session with a password for the calling cPanel user to connect to Webmail.

Note:

  • The cPanel user must own the Webmail account.
  • This function works like the UAPI Session::create_webmail_session_for_mail_user function with one exception. This function requires a correct password to create the Webmail session. If you use an incorrect password or attempt to connect to a suspended account, the login will fail.

### How to use this API

After you successfully call this API, you will need to log in to Webmail. To do this, send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:

  • $URL_AUTHTY represents the value from the hostname return.
  • If the hostname return value is null, enter the hostname of the server that answered the API function.
  • $token represents the value from the token return.
  • $session represents the value of the session return.

For example, an HTTP POST may resemble the following:

``https://hostname.example.com:2096/cpsess2462418786/login``

With a message body of:

``session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137``

domainstringRequired
The domain for the Webmail account.
loginstringRequired
The Webmail account's username.
passwordstringRequired
The password for the Webmail account.
localestringOptional
The locale that the new session will use. Note: You must only enter lowercase characters. This parameter defaults to the cPanel user's locale.
remote_addressstringOptional
The session's account's client IP address. Note: If you run this function from the command line, this parameter is required. This parameter defaults to the API caller's IP address.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

hostnamestring
The Webmail server's hostname. Note: The function returns a null value when the Webmail server is not remote.
sessionstring
The session value to submit via POST to begin using the new session.
tokenstring
A new security token.

create_webmail_session_for_self GET#

Create Webmail session for current user

Create a temporary session to connect to Webmail for the authenticated cPanel user.

### How to use this API

After you successfully call this API, you will need to log in to Webmail. To do this, send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:

  • $URL_AUTHTY represents the value from the hostname return.
  • If the hostname return value is null, enter the hostname of the server that answered the API function.
  • $token represents the value from the token return.
  • $session represents the value of the session return.

For example, an HTTP POST may resemble the following:

``https://hostname.example.com:2096/cpsess2462418786/login``

With a message body of:

``session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137``

localestringOptional
The locale that the new session will use. Use UAPI Locale::list_locales to see a list of valid locales. Note: You must only enter lowercase characters. This parameter defaults to the cPanel user's locale.
remote_addressstringOptional
The session's client IP address. Note: If you run this function from the command line, this parameter is required. This parameter defaults to the API caller's IP address.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

hostnamestring
The Webmail server's hostname. Note: The function returns a null value when the Webmail server is not remote.
sessionstring
The session value to submit via POST to begin using the new session.
tokenstring
A new security token.