Authenticating API Function Calls

This document describes various methods of authenticating API function calls in cPanel and WHM.

About authenticating function calls

In order to perform function calls using the cPanel and WHM API, you will need to access your server with the correct permissions.

When you perform function calls in a browser, you can authenticate simply by logging into WHM or cPanel. Then, you can access a URL such as https://example.com:2087/xml-api/functionname, where example.com stands for your server's hostname or IP address, and functionname stands for the function you wish to access.

However, calling a function through a web browser is mainly useful for testing. The most powerful application of our API functions occur when they are incorporated into users' custom scripts. From within these scripts, there are 2 main ways of authenticating, outlined below.

Basic user/password authentication

You can write your script so that it includes a username and password in the HTTP header that it sends to the server when it calls the API function.

Warning: Do not perform authentication this way over an unsecured connection (using port 2086 or 2082). Using this method over an unsecured connection can compromise your server.

Sample Perl script

In a Perl script, the authentication code would look similar to the following example:

#!/usr/bin/perl
use strict;
use LWP::UserAgent;
use MIME::Base64;

my $user = "root";
my $pass = "password";

my $auth = "Basic " . MIME::Base64::encode( $user . ":" . $pass );

print $auth;

my $ua = LWP::UserAgent->new;
my $request =
  HTTP::Request->new( GET => "http://127.0.0.1:2086/xml-api/listaccts" );
$request->header( Authorization => $auth );
my $response = $ua->request($request);
print $response->content;

Sample PHP script

In a PHP script, the authentication code would look similar to the following example:

<?

$whmusername = "username";
$whmpassword = "password"

$query = "https://127.0.0.1:2087/";

$curl = curl_init();		
# Create Curl Object
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,0);	
# Allow self-signed certs
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,0); 	
# Allow certs that do not match the hostname
curl_setopt($curl, CURLOPT_HEADER,0);			
# Do not include header in output
curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);	
# Return contents of transfer on curl_exec
$header[0] = "Authorization: Basic " . base64_encode($whmusername.":".$whmpassword) . "\n\r";
curl_setopt($curl, CURLOPT_HTTPHEADER, $header);  
# set the username and password
curl_setopt($curl, CURLOPT_URL, $query);			
# execute the query
$result = curl_exec($curl);
if ($result == false) {
	error_log("curl_exec threw error \"" . curl_error($curl) . "\" for $query");	
# log error if curl exec fails
}
curl_close($curl);

print $result;

?>

Access hash authentication

You can write your script so that it includes an access hash, or "key," in the HTTP header that it sends to the server when it calls the API function. This method is only available to WHM users.

The access hash can be set up, and subsequently accessed, from the WHM Setup Remote Access Key feature. On your server, the hash resides in /root/.accesshash.

Note: We recommend using this method over the username/password method, as the access hash method is inherently more secure.

Sample Perl script

In a Perl script, the authentication code would look similar to the following example:

#!/usr/bin/perl
use strict;
use LWP::UserAgent;

my $hash = "3a8de68846a297de51f3921663972196
a298d16cc18ed4f9577753fc48e49917
3bd713ddfea78defc41c90cfe5aab2c7
7ff17d5c725efbc8fe058ba29b00d19f
6d6ea1848589e4312d3e13f2f44aa271
9bf5c4e15862be76ac39b201518961c6
581fa92b8ca67b53ef9b5ad331a3f845
586828f76b7e9cbba5ea7ae348d1207c
dfdc0548c67bc46e13cd52d485b91b01
de43080c01d35e7cdfb9be3fb2925c85
616f599f109a1d5cd69a7171e8ed91d2
528bd0b8c162a395c8f50d7b01dd0918
b3573497549c5796926e50cd712d0c73
39a1403cc1a70ff8ed426c34320cdeaa
e8190477c1fef7f300497176b34ebcca
87d014ac1c3c6d4fc33542ad8e5685c4
32f1303ff82ef50ebdcceaebd979656b
9798128753e538785bd931f915870359
9efb1ec80594160bba985fd8b3395fc9
58cda7cf250eea7a0d760fb9c3cd0232
6b8c720990e472bd369a75ec56ec9097
22b8800f93269cbcf73ac5b6a255f7e9
7dfce8543e4d7d0778c9e80ebbb97444
c39a16b41c3b7fd40140c407d13c7c71
75a3a6e37f4c8f85fe534c4cade7b220
6537bb25435a0d38bf54d20bea0ddce5
e07b17ccf9feb4285254ecb1e7f00e4f
e821e5fdc0a81d531f3a8abc9848de63
998f28e37f5e50d93eab5a24cdb2bb28";

$hash =~ s/\n//g;

my $auth = "WHM root:" . $hash;

my $ua = LWP::UserAgent->new;
my $request =
  HTTP::Request->new( GET => "http://127.0.0.1:2086/xml-api/listaccts" );
$request->header( Authorization => $auth );
my $response = $ua->request($request);
print $response->content;

Sample PHP script

In a PHP script, the authentication code would look similar to the following example:

<?

$whmusername = "root";
$whmhash = "somelonghash";     # some hash value

$query = "https://127.0.0.1:2087/....";

$curl = curl_init();																												# Create Curl Object
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,0);																# Allow certs that do not match the domain
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,0);																# Allow self-signed certs
curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);																# Return contents of transfer on curl_exec
$header[0] = "Authorization: WHM $whmusername:" . preg_replace("'(\r|\n)'","",$whmhash);	# Remove newlines from the hash
curl_setopt($curl,CURLOPT_HTTPHEADER,$header);															# Set curl header
curl_setopt($curl, CURLOPT_URL, $query);																		# Set your URL
$result = curl_exec($curl);																									# Execute Query, assign to $result
if ($result == false) {
	error_log("curl_exec threw error \"" . curl_error($curl) . "\" for $query");
}
curl_close($curl);

print $result;

?>

Additional resources

These authentication functions are also implemented in the cPanel/WHM "Accounting" modules, which are installed on your server in the /usr/local/cpanel/Cpanel/Accounting/ directory. Feel free to view these modules for more insight into how to structure your scripts.