Child pages
  • WHM API 1 Functions - create_user_session
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 to log in to third-party applications (for example, billing systems) without storing 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=Backups_Home&preferred_domain=example.com
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/create_user_session?api.version=1&user=username&service=cpaneld&locale=fr&app=Backups_Home&preferred_domain=example.com
 Command Line
whmapi1 create_user_session user=username service=cpaneld locale=fr app=Backups_Home preferred_domain=example.com


Notes:

  • Unless otherwise noted, 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.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 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 (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
userstring

Required

The session's user.

  • A valid cPanel account username.
  • A valid email address — We introduced this value in cPanel & WHM version 11.44.


user

or

user@example.com

service string

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
locale string

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 application names, to link the session to an application:

     cPanel Applications
    • 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
     WHM Applications
    • add_a_dns_zone
    • add_an_a_entry_for_your_hostname
    • add_a_new_ip_address
    • add_a_package
    • additional_mysql_access_hosts
    • add_remove_recognized_ip_addresses
    • apache_configuration
    • apache_mod_userdir_tweak
    • apache_status
    • api_shell
    • api_tokens
    • apps_managed_by_appconfig
    • assign_ipv6_address
    • background_process_killer
    • backup_configuration
    • backup_restoration
    • backup_system_migration
    • backup_user_selection
    • basic_webhost_manager_setup
    • blocker
    • change_account_contact_email
    • change_hostname
    • change_log
    • change_multiple_sites_ip_addresses
    • change_mysql_user_password
    • change_ownership_of_an_account
    • change_ownership_of_multiple_accounts
    • change_root_password
    • change_sites_ip_address
    • change_webhost_manager_theme
    • cloudlinux_lve_manager
    • compiler_access
    • configuration_cluster
    • configure_application_locales
    • configure_cpanel_analytics
    • configure_cpanel_cron_jobs
    • configure_postgresql
    • configure_remote_service_ips
    • configure_security_policies
    • contact_manager
    • convert_addon_domain_to_account
    • copy_a_locale
    • copy_an_account_from_another_server_with_an_account_password
    • cpanel_development_forum
    • cpanel_log_rotation_configuration
    • cpanel_plugin_file_generator
    • cpanel_web_disk_configuration
    • cpanel_web_services_configuration
    • cphulk_brute_force_protection
    • create_a_new_account
    • create_support_ticket
    • customization
    • daily_process_log
    • database_map_tool
    • delete_a_dns_zone
    • delete_a_locale
    • delete_a_package
    • directoryindex_priority
    • dns_cluster
    • dns_server
    • easyapache_4
    • edit_a_locale
    • edit_a_package
    • edit_backup_mx_hosts
    • edit_blacklisted_smtp_ips
    • edit_dns_zone
    • edit_mx_entry
    • edit_only_verify_recipient_smtp_hosts
    • edit_questions_and_answers
    • edit_reseller_name_servers_and_privileges
    • edit_sender_verification_bypass_ips
    • edit_system_mail_preferences
    • edit_trusted_smtp_ips
    • edit_zone_templates
    • email_all_resellers
    • email_all_users
    • email_deliverability
    • enable_dkim_and_spf_globally
    • exim_configuration_manager
    • feature_manager
    • file_and_directory_restoration
    • forceful_server_reboot
    • force_password_change
    • ftp_server_configuration
    • ftp_server_proftpd_pureftpd
    • ftp_server_selection
    • generate_an_ssl_certificate_and_signing_request
    • global_configuration
    • graceful_server_reboot
    • grant_cpanel_support_access
    • greylisting
    • host_access_control
    • http_server_apache
    • ico-security-advisor
    • imap_server
    • include_editor
    • initial_quota_setup
    • install_an_rpm
    • install_an_ssl_certificate_on_a_domain
    • install_a_perl_module
    • install_a_perl_module_process
    • install_cpaddons_site_software
    • ip_migration_wizard
    • ipv6_ranges
    • legacy_backup_configuration
    • legacy_language_file_upload
    • legacy_restore_backups
    • legacy_restore_multiple_backups
    • legacy_restore_multiple_backups_confirmation
    • limit_bandwidth_usage
    • list_accounts
    • list_parked_domains
    • list_subdomains
    • list_suspended_accounts
    • locale_editor
    • locale_xml_download
    • locale_xml_upload
    • log_rotation
    • mailbox_conversion
    • mail_delivery_reports
    • mailing_list_manager_mailman
    • mail_queue_manager
    • mailserver_configuration
    • mail_server_exim
    • mail_troubleshooter
    • manage_account_suspension
    • manage_autossl
    • manage_compiler_group
    • manage_cpaddons_site_software
    • manage_custom_rbls
    • manage_databases
    • manage_database_users
    • manage_demo_mode
    • manage_external_authentication
    • manage_external_authentication_providers
    • manage_external_authentication_users
    • manage_hooks
    • manage_mysql_profiles
    • manage_plugins
    • manage_resellers_ip_delegation
    • manage_resellers_shared_ip
    • manage_roots_ssh_keys
    • manage_services_ssl_certificates
    • manage_shell_access
    • manage_ssl_hosts
    • manage_wheel_group_users
    • market_provider_manager
    • memory_usage_restrictions
    • modify_an_account
    • modify_cpanel_whm_news
    • modify_upgrade_multiple_accounts
    • modsecurity_configuration
    • modsecurity_tools
    • modsecurity_vendors
    • module_installers
    • multiphp_ini_editor
    • multiphp_manager
    • mysql_mariadb_upgrade
    • mysql_root_password
    • nameserver_record_report
    • nameserver_selection
    • non_standard_locale_configuration
    • park_a_domain
    • password_modification
    • password_strength_configuration
    • perform_a_dns_cleanup
    • php_fpm_service_for_apache
    • phpMyAdmin
    • piped_log_configuration
    • process_manager
    • purchase_and_install_an_ssl_certificate
    • quota_modification
    • raw_apache_log_download
    • raw_ftp_log_download
    • rearrange_an_account
    • rebuild_rpm_database
    • rebuild_the_ip_address_pool
    • remote_access_key
    • repair_a_mysql_database
    • repair_mailbox_permissions
    • reseller_center
    • reserved_ips_editor
    • reset_account_bandwidth_limit
    • reset_a_dns_zone
    • reset_a_mailman_password
    • reset_resellers
    • resolver_configuration
    • restore_a_full_backup_cpmove_file
    • restore_modules_summary
    • review_transfers_and_restores
    • security_questions
    • server_information
    • server_profile
    • server_time
    • service_manager
    • service_status
    • setup_edit_domain_forwarding
    • set_zone_time_to_live_ttl
    • shell_fork_bomb_protection
    • show_accounts_over_quota
    • show_current_disk_usage
    • show_current_running_processes
    • show_edit_reserved_ips
    • show_ip_address_usage
    • show_mysql_processes
    • show_or_delete_current_ip_addresses
    • show_reseller_accounts
    • skeleton_directory
    • smtp_restrictions
    • software_development_kit
    • spamd_startup_configuration
    • sql_server_mysql
    • sql_server_pgsql
    • ssh_password_authorization_tweak
    • ssh_server_openssh
    • ssl_storage_manager
    • statistics_software_configuration
    • support_center
    • synchronize_dns_records
    • system_update
    • task_queue_monitor
    • terminal
    • terminate_accounts
    • theme_manager
    • tomcat_manager
    • traceroute_enable_disable
    • transfer_tool
    • tweak_settings
    • two_factor_authentication
    • unsuspend_bandwidth_exceeders
    • update_database_map
    • update_database_map_process
    • update_preferences
    • update_server_software
    • upgrade_downgrade_an_account
    • upgrade_to_latest_version
    • view_available_locales
    • view_bandwidth_usage
    • view_mail_statistics_summary
    • view_relayers
    • view_reseller_usage_and_manage_account_status
    • view_sent_summary
    • web_template_editor
  • An invalid application name, to create the session but not link it to an application.

Backups_Home

preferred_domainstring

The hostname that you wish for the function to use in the url return.

This parameter's value defaults to the server's hostname.

  • A valid domain that exists on the server.
  • An IP address that exists on the server.
example.com

Returns

ReturnTypeDescriptionPossible valuesExample
sessionstring

The session ID.

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

username:RFw6MUp9S8sRwTSgqaUJWUCq8ZQg2Zkopx5KaTHRNQXBfT3n8xvfBEF9JJC3iiwa

service string 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
url string The security token's URL.

A valid URL that contains the preferred_domain, session, and app values.

Note:

  • In cPanel & WHM version 78, if the hostname does not have a configured Domain Name System (DNS), the system returns an IP address.
  • 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