- Created by Documentation, last modified on Apr 09, 2018
Introduction
Use API tokens to authenticate to execute WHM API 1 functions over HTTPS.
Important:
- We introduced this functionality in cPanel & WHM version 64.
- 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.
Permission denied
orFunction not found
errors if they use an incorrect port number. - This document only includes cPanel & WHM authentication methods. For Manage2 authentication information, read our Guide to the Manage2 API documentation.
API tokens
API tokens allow you to log in to the server without the need for a password. You can use an API token to authenticate with WHM’s APIs.
To create an API token, use WHM's Manage API Tokens interface (WHM >> Home >> Security Center >> Manage API Tokens). Then, include that API token in your custom code.
Warning:
Make certain that you save your API token in a safe location on your workstation so you can use it with other features. You cannot access the token after you navigate away from the interface or refresh the API Tokens table.
Example Perl script
Notes:
Specify either the
root
user or a reseller user in line 9.- Replace
MYAPITOKEN
in line 10 with a valid API token. - Replace
127.0.0.1
in line 18 with your server's IP address.
#!/usr/bin/perl use strict; use warnings; use JSON (); use HTTP::Tiny (); my $user = 'root'; my $token = 'MYAPITOKEN'; my $ua = HTTP::Tiny->new( 'verify_SSL' => 0, 'default_headers' => { 'Authorization' => "whm $user:$token", }, ); my $response = $ua->get("https://127.0.0.1:2087/json-api/listaccts?api.version=1"); if ( $response->{'success'} ) { my $json = JSON::decode_json( $response->{'content'} ); print "[+] Current cPanel users on the system:\n"; print "\t$_\n" for map { $_->{'user'} } @{ $json->{'data'}->{'acct'} }; } else { print "[!] Error: $response->{'status'} $response->{'reason'} returned\n"; }
- In line 10, the script declares the
$token
variable and assigns the API token hash to it as a value. - In line 11, the script creates an
HTTP::Tiny
user agent and configures it to send the token authorization headers with every request. - Line 18 invokes the WHM API 1
listaccts
function via theHTTP::Tiny
user agent and saves the response in the$response
variable. - The script prints the following output:
- If the
listacct
function succeeds, the function parses the JSON data and returns the account's usernames. - If the
listacct
function fails, the function returns an error message.
- If the
Example PHP script
Notes:
Specify either the
root
user or a reseller user in line 2.- Replace
MYAPITOKEN
in line 3 with a valid API token. - Replace
127.0.0.1
in line 5 with your server's IP address.
<? $user = "root"; $token = "MYAPITOKEN"; $query = "https://127.0.0.1:2087/json-api/listaccts?api.version=1"; $curl = curl_init(); curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,0); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,0); curl_setopt($curl, CURLOPT_RETURNTRANSFER,1); $header[0] = "Authorization: whm $user:$token"; curl_setopt($curl,CURLOPT_HTTPHEADER,$header); curl_setopt($curl, CURLOPT_URL, $query); $result = curl_exec($curl); $http_status = curl_getinfo($curl, CURLINFO_HTTP_CODE); if ($http_status != 200) { echo "[!] Error: " . $http_status . " returned\n"; } else { $json = json_decode($result); echo "[+] Current cPanel users on the system:\n"; foreach ($json->{'data'}->{'acct'} as $userdetails) { echo "\t" . $userdetails->{'user'} . "\n"; } } curl_close($curl); ?>
- Line 2 sets the
$user
value as theroot
user. - Line 3 sets the
$token
value as the contents of the appropriate API token. Line 5 initializes the WHM API 1
listaccts
function via acurl
call and configures it to send theAuthorization: token $user:$token
headers with every request.- Line 16 performs the WHM API 1
listaccts
function via acurl
call and saves the response in the$response
variable. - The script prints the following output:
- If the
listacct
function succeeds, the function parses the JSON data and returns the account's usernames. - If the
listacct
function fails, the function returns an error message.
- If the
Related documentation
-
Page:Manage2 API Functions - Add a Pickup Phrase — This function creates a pickup phrase that you use to authenticate with the Manage2 API.
-
Page:Manage2 API Functions - Register Key-Based Authentication — This function registers a server to use keyed authentication.
-
Page:Manage2 API - Authentication Methods — The Manage2 API supports HTTP or key-based authentication.
-
Page:Guide to API Authentication — cPanel & WHM supports several API authentication methods.
-
Page:Guide to External Authentication - OpenID Connect — External authentication allows your server's users to log in to WHM, cPanel, and Webmail through OpenID Connect-compliant identity providers.