Trouble with understanding tokens


Jul 7, 2017
cPanel Access Level
Reseller Owner
hi all,

sorry for noob question this is the first time looking at the WHM API.

im making an app and i want it to connect to the WHM API to create new accounts ect. after hours of trying (and failing) my hosting company told me to use the cpsess####### after logging in to access the api and that worked. the only problem is that to my understanding that number is generated for the session, so it wont work in different browsers, on different computers or at different times. this is a problem for me as my app will be used by lots of different people on different clients.

to my understanding i need to use the API Token feature which i have done however replacing cpsess with that does not work, i get the error "Token Denied." after doing some research i came across the create_user_session function, i might be reading it wrong but i think this should take the API Token and convert it or generate a cpsess######, however in the example it requires the cpsess######## so that doesnt work for me.

my goal is to be able to access the WHM API using the static API Token that i can put in the app.

any assistance will be greatly appreciated.


Staff member
Apr 11, 2011

Could you provide us with a step-by-step list of the actions you are taking so we can attempt to reproduce the issue?


Spork Schivago

Well-Known Member
Jan 21, 2016
corning, ny
cPanel Access Level
Root Administrator

I use tokens to access WHM's API calls as root in a perl script I wrote. This is how I do it.

First, log into WHM and create the token under Home >> Development >> Manage API Tokens.

I click on Generate Token and give it a good name, something that might help you remember what the token is for...After hitting Generate Token, it'll ask you to copy and save the token. This is important. If someone gains access to your token, they'll essentially have root access to WHM.

Now, in my perl script, I use it like so:

# A simple perl script that demonstrates how to use a WHM
# API token to list user accounts.

use strict;
use LWP::UserAgent;
use LWP::Protocol::https;
use MIME::Base64;
use IO::Socket::SSL;
use URI::Escape;

# Setup a variable to hold the username we're going to log into WHM as.
my $user = 'root';

# Setup a variable to hold the username we want to search for (* = all).
my $username = '*';

# Use the API token instead of a password or access hash.
my $token = '<my access token>';

# Setup a variable to hold the authorization string.
my $auth = "WHM " . $user . ":" . $token;

# Setup the user agent.
my $ua = LWP::UserAgent->new(
    ssl_opts   => { verify_hostname => 0, SSL_verify_mode => 'SSL_VERIFY_NONE', SSL_use_cert => 0 },

# list cPanel accounts.
print "Attempting to list all accounts...\n";
my $request = HTTP::Request->new( POST => "$username&searchtype=user" );
$request->header( Authorization => $auth );
my $response = $ua->request($request);
print $response->content;
Where <my access token> is replaced with my actual token that I copied and pasted. I make the file executable by doing something like:
chmod 700 ./
Then when I execute ./, I see all the accounts on my system.

You would do something similar, but replace
my $request = HTTP::Request->new( POST => "$username&searchtype=user" );
with something like:
my $request = HTTP::Request->new( POST => "" );
You'd obviously probably not hardcode the username and stuff like that. You'd probably want to use some variables, like $username, $domainname, $password, etc.

If you need an example to create a certain account, let me know, and I'll try to create one for you. Just give me stuff like the username you want, the domain name, etc. But I think you'll be able to figure it out with the info I shared. If you have any questions, please let me know.

I suggest just starting with the listaccts example I posted, just so you can verify you're logging into WHM as root successfully and you're able to call at least the listaccts API. After that, you can just modify the code and play around with various other API calls.