Guide to API Authentication

Introduction

cPanel & WHM supports several API authentication methods. Whenever code calls an API function, it must first authenticate to the server. The authentication process accesses the server in order to run code as a specific cPanel or WHM user with a specific set of permissions.

Important:

API calls that use a method that includes a URL must use the correct port:

  • 2082 — Unsecure calls to cPanel's APIs.
  • 2083 — Secure calls to cPanel's APIs.
  • 2086 — Unsecure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
  • 2087 — Secure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
  • 2095 — Unsecure calls to cPanel's APIs via a Webmail session.
  • 2096 — Secure calls to cPanel's APIs via a Webmail session.

Otherwise-correct calls will return Permission denied or Function not found errors if they use an incorrect port number. 

Browser-based authentication

To call API functions through a web browser, you must first log in to WHM or cPanel.

  • The API function determines which cPanel, Inc. product to log in to.
  • Some functions require specific feature lists or user permissions.

Access hash authentication

Note:

This method is only available for WHM authentication. Applications and scripts must authenticate as the root user in order to use this method.

An access hash is a key that authenticates with the server as the root user. Scripts can include an access hash in the HTTP header that they send to the server during API functions.

  • To view or retrieve an access hash, use WHM's Remote Access Key interface (Home >> Clusters >> Remote Access Key).
  • The system stores access hashes in the .accesshash file in each user's home directory.

Username and password authentication

Warning:

Do not use this method to authenticate over an unsecured connection (port 2086, 2095, or 2082). Only use this method with a secure SSL connection over port 2083 (cPanel), port 2096 (Webmail), or port 2087 (WHM). 

Scripts can include the username and password in an HTTP header. The script sends an HTTP header to the server during API functions. This allows the script to effectively log in as the desired user before the function.

Two-factor authentication

Important:

We introduced this feature in cPanel & WHM version 54.

The Two-Factor Authentication feature requires an additional six-digit security code to log in to cPanel & WHM. A smartphone with a supported time-based one-time password (TOTP) app provides the security code.

2FA with Session-based Authentication

This script sends the OTP once to establish an authenticated session, and then performs all of the API calls within that session.

2FA with Basic HTTP Authentication, Not Session-based

This script allows you to perform API calls without establishing a session, but it requires you to send the OTP token with every request in the X-CPANEL-OTP header. This script also requires that you know the 2FA secret in order to generate the required tokens.

Single Sign On

Important:

We introduced this feature in cPanel & WHM version 11.40.

The Single Sign On feature generates a temporary session to authenticate with cPanel & WHM.

For example, this feature generates a temporary session whenever the root user or a reseller uses the following methods to access a cPanel user's account:

  • WHM's List Accounts interface (Home >> Account Information >> List Accounts).
  • WHM API 1's create_user_session function.

Third-party applications with WHM access can use this feature to log in to cPanel accounts without the need to store their account passwords. The system automatically destroys the temporary session when it logs out or expires (sessions expire after 15 minutes of inactivity). This feature also creates temporary sessions when a cPanel user logs in to Webmail through the cPanel interface.

To use this method, perform the following steps:

  1. Call WHM API 1's create_user_session function.

  2. Send a GET request to the URL that the function returns as the url value.

    Note:

    The session will not function until you send this request. The GET request to the login URL returns a cookie that must exist for subsequent API calls to authenticate successfully. 

  3. Configure your script to use the temporary session ID and security token to access the account through either the access hash or username and password methods.

The Single Sign On session log

Whenever the Single Sign On feature generates or destroys a temporary session, the system stores information to the Single Sign On session log:

1
2
3
4
127.0.0.1 [12/05/2013:06:36:09 -0000] PURGE fz49w:ym5mFKRIAChAQ_yHyn6i19p6DQupDepQN4I3HnH490AAWPFSP2ZipQ7YpE_uA_CG logout
127.0.0.1 [12/05/2013:06:36:12 -0000] NEW z2p:BADVVmryioLExTGvKITEbSuDFHztNAyEeetBPpUmA8sA8Iu_y4eofHZmbbzIG2UU address=127.0.0.1,app=cpaneld,creator=z2p,method=handle_form_login,path=form,possessed=0
127.0.0.1 [12/05/2013:06:36:13 -0000] PURGE z2p:BADVVmryioLExTGvKITEbSuDFHztNAyEeetBPpUmA8sA8Iu_y4eofHZmbbzIG2UU loginsucess
127.0.0.1 [12/05/2013:06:36:13 -0000] NEW z2p:qgBu2rqQh_9R4tDhD2qgqVx0Oy21Ezy6_E581eYvBv0AbuA5oMZAWw_l0vahOhiH address=127.0.0.1,app=cpaneld,creator=z2p,method=handle_form_login,path=form,possessed=0

The system logs the following types of entries:

  • NEW  — The system logs a NEW entry for each new temporary session.
  • PURGE  — The system logs a PURGE entry each time that it removes a temporary session.

NEW entries

NEW entries include the following information in a comma-separated list:

Key

Description

Possible values

Example

 (Session ID) 

The session ID that the system created.

Note:

 Unlike other log entry items, the session ID does not appear in key=valueformat. 

A valid session ID.

 

address

The IP address that requested the session.

A valid IP address.

127.0.0.1

app

The application that created the session.

A valid application or service name.

cpaneld

creator

The WHM account that created the session.

A valid WHM username.

z2p

method

The method through which the user created the session.
  • handle_form_login — The creator logged in from a login form.
  • handle_auth_transfer — The creator logged in through a cPanel & WHM interface.

 handle_form_login 

path

The path to the process that created the session.
  • A valid path.
  • form — The creator logged in from a login form.

form

possessed

Whether the session runs with another user's privileges (impersonation).
  • 1 — The session runs with another user's privileges.
  • 0 — The session runs with the creator's privileges.

0

 

PURGE entries

PURGE entries include the session ID, and one of the following reason codes:

 Reason code 

Description

badpass

The temporary session authentication failed.

expired

The session expired.

kill

The system stopped the session but did not provide a reason.

loadsession

 The creator logged in with a session token that the system destroyed when it created the new session. 

loginsuccess

The creator logged in successfully and the system created a new session.

logout

The creator logged out.

xfercpanel

WHM transferred the session to cPanel.

xferwebmail

cPanel transferred the session to Webmail.

xferwhm

cPanel transferred the session to WHM.

 

Secure remote logins

To allow users to log in to cPanel & WHM remotely, write a script that calls the Cpanel::LogMeIn module's get_loggedin_url() subroutine. This subroutine returns a URL for remote logins to cPanel, WHM, or Webmail.

  • In cPanel & WHM version 11.38.0 and earlier, the URL is a single-use URL.
  • cPanel & WHM version 11.38.1 introduced reusable remote login URLs. These URLs expire when the user logs out, or after a normal session timeout.

Parameters

When you call the get_loggedin_url() subroutine, you must pass in the following parameters:

 Parameter 

 Type 

Description

Possible values

Example

user

string

Required

The cPanel, WHM, or Webmail username.

A valid username.

In most scripts, retrieve this value from user input.

username

pass

string

Required

The account's password.

A secure password.

In most scripts, retrieve this value from user input.

12345luggage

hostname

string

Required

The cPanel, WHM, or Webmail account's main domain.

A valid domain on the server.

example.com

service

string

Required

The account's service type.
  • cpanel
  • whm
  • webmail

cpanel

goto_uri

string

Required

 The location to which the script will redirect the user. The get_loggedin_url()subroutine uses this value to create the URL. 

 A valid path, relative to the/usr/local/cpanel/base/directory. 

 /frontend/x3/park/index.html 

 

Returns

The get_loggedin_url() subroutine returns the following values:

Return

Type

Description

Possible values

Example

login_ok

 boolean 

 Whether the function authenticated the user successfully. 
  • 1 — Success.
  • 0 — Failure.

1

 login_message 

string

A status message from the subroutine.
  • Login OK
  • An error message.

Login OK

login_url

string

The secure remote login URL.

 A valid URL that includes a valid session token and directs the user to thegoto_uripath. 

 https://example.com:2083/cpsess##########/frontend/x3/park/index.html 

 

 

 

  • 14 Users Found This Useful
Was this answer helpful?

Related Articles

The cPanel Interface

For  cPanel  &  WHM  version  58 Overview The cPanel interface is...

User Preferences

For cPanel & WHM version 58 Overview This document outlines how to access your cPanel...

Manage External Authentications

For cPanel & WHM version 58 Overview Manage credentials Additional documentation...

What is cPanelID?

In This Article:  Overview ServicesHow to get a cPanelID cPanelID External...

Guide to cPanel Interface Customization - cPanel Style Development

Introduction You can develop custom styles that modify the appearance of the cPanel interface....