Guide to API Authentication - API Tokens

Guide to API Authentication

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.
Otherwise-correct calls will return Permission denied or Function 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

Click to view...

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 the HTTP::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.

Example PHP script