Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function creates a new temporary user session for a specified service. This allows users with WHM access (with a password, access hash, or API token) to log in to third-party applications, such as billing systems, without the need to store the account password.

Notes:

  • The system destroys the temporary session after 15 minutes of inactivity.
  • For more information about the Single Sign On feature, read our Guide to API Authentication documentation.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/create_user_session?api.version=1&user=username&service=cpaneld&locale=fr&app=awstats
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/create_user_session?api.version=1&user=username&service=cpaneld&locale=fr&app=awstats
 Command Line
whmapi1 create_user_session user=username service=cpaneld locale=fr app=awstats

Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 Output (JSON)
{
  "data": {
    "cp_security_token": "/cpsess1234567890",
    "expires":1401993893,
    "session": "username:GHehYZ1GCxzmDATMmT1xT4rN0tiPGMWnKErPJdU3t6AGBx2LjQ3qB6Xih5naUh_4:create_user_session,
	5dc619831bac4aa2e014e062d762645e8447949eaef14fc53a8ce2b1e0e2592a",
    "url":
"https://example.com:2083/cpsess1234567890/login/?
	goto_uri=frontend%2fx3%2fstats%2fawstats_landing.html&locale=fr&session=username:%3aGHehYZ1GCxzmDATMmT1xT4rN0tiPGMWnKErPJdU3t6AGBx2LjQ3qB6Xih5naUh_4%3acreate_user_session%2c5dc619831bac4aa2e014e062d762645e8447949eaef14fc53a8ce2b1e0e2592a",
	"locale":"fr",    
	"service": "cpaneld"
  },
  "metadata": {
    "version": 1,
    "reason": "Created session",
    "result": 1,
    "command": "create_user_session"
  }
}
 Output (XML)
<result>
    <data>
        <session>
            username:RFw6MUp9S8sRwTSgqaUJWUCq8ZQg2Zkopx5KaTHRNQXBfT3n8xvfBEF9JJC3iiwa
        </session>
        <expires>1401993893</expires>
        <url>
            https://example.com:2083/cpsess1234567890/login/?session=username:RFw6MUp9S8sRwTSgqaUJWUCq8ZQg2Zkopx5KaTHRNQXBfT3n8xvfBEF9JJC3iiwa&locale=fr&app=awstats
        </url>
        <service>cpaneld</service>
        <cp_security_token>/cpsess1234567890</cp_security_token>
    </data>
    <metadata>
        <reason>Created session</reason>
        <version>1</version>
        <result>1</result>
        <command>create_user_session</command>
    </metadata>
</result>

Note:

Use WHM's API Shell interface (Home >> Development >> API Shell) to directly test WHM API calls.

     

Parameters

ParameterTypeDescriptionPossible valuesExample
userstring

Required

The session's user.

A valid cPanel account's username.
user
servicestring

Required

The session's service.

  • cpaneld
  • whostmgrd — We introduced this value in cPanel & WHM version 11.44.
  • webmaild We introduced this value in cPanel & WHM version 11.44.
cpaneld
localestring

The session's locale.

If you specify a locale, the server sends a cookie to your browser with that locale setting.

  • The cookie expires after one year. 
  • Users can change the locale with the language options at the bottom of the login interface.

A valid locale abbreviation.

fr
appstring

The application to which the session will link.

Note:

We introduced this parameter in cPanel & WHM version 11.50 in order to allow WHM users to directly access an application's interface as the specified cPanel user. 

  • One of the following valid application names, to link the session to an application:
      • Backups_Home
      • Calendar_Configure
      • ContactInfo_Change
      • Cron_Home
      • Database_MySQL
      • Database_phpMyAdmin
      • Domains_AddonDomains
      • Domains_SubDomains
      • Email_AccountLevelFiltering
      • Email_Accounts
      • Email_Archive
      • Email_Authentication
      • Email_AutoResponders
      • Email_BoxTrapper
      • Email_DefaultAddress
      • Email_DeliveryReport
      • Email_Forwarders
      • Email_GreyListing
      • Email_MailingLists
      • Email_MX
      • Email_SpamFilter
      • Email_UserLevelFiltering
      • FileManager_Home
      • Locale_Change
      • Password_Change
      • Site_Software
      • Site_Software_*
      • Stats_AWStats
      • WHMCS_billing
  • An invalid application name, to create the session but not link it to an application.
awstats

Returns

ReturnTypeDescriptionPossible valuesExample
sessionstring

The session ID.

The cPanel account username, a colon, and a unique string of characters.
 Click to view...

username:RFw6MUp9S8sRwTSgqaUJWUCq8ZQg2Zkopx5KaTHRNQXBfT3n8xvfBEF9JJC3iiwa

servicestring The security token's service.
  • cpaneld
  • whostmgrd
  • webmaild
cpaneld
cp_security_tokenstringThe session's security token.A valid string.
/cpsess1234567890
expiresstringWhen the security token expires.A valid date in Unix time format.
1401993893
urlstring The security token's URL.

A valid URL that contains the session or app values.

Note:

In cPanel & WHM version 11.50 and later, if the app parameter contains a valid application, this URL contains application information.

 Click to view...

https://example.com:2083/cpsess1234567890/login/?session=username:RFw6MUp9S8sRwTSgqaUJWUCq8ZQg2Zkopx5KaTHRNQXBfT3n8xvfBEF9JJC3iiwa&locale=fr

 Click to view (valid application)...
https://example.com:2083/cpsess1234567890/login/?goto_uri=frontend%2fx3%2fstats%2fawstats_landing.html&locale=en&session=username%3aGHehYZ1GCxzmDATMmT1xT4rN0tiPGMWnKErPJdU3t6AGBx2LjQ3qB6Xih5naUh_4%3acreate_user_session%2c5dc619831bac4aa2e014e062d762645e8447949eaef14fc53a8ce2b1e0e2592a
 Click to view (invalid application)...
https://example.com:2083/cpsess1234567890/login/?locale=en&session=username%3agmQL86v3f9hZwp9EHwnRJIdCAVyvo1Tr8cQfGTi2BMp1Q5MLkk6VDJC02Ql795B0%3acreate_user_session%2cf822158f359f63d6427dc4913aea72315b5baf20cfa05a65a54a542a308b01f0