Development Guides Home >> Guide to API Authentication

Guide to API Authentication - API Tokens in WHM

Introduction

API tokens allow you to call WHM API 1 functions outside of a WHM session. You can use API tokens instead of a password or access hash key to call WHM API 1 functions over HTTPS. This is useful, for example, to allow a reseller user or third-party developer to run API function calls with your account's data.

Creating an API token

To create an API token, use WHM's Manage API Tokens interface (WHM >> Home >> Development >> Manage API Tokens). You can also use the WHM API 1 api_token_create function.

Using an API token

To call a WHM API 1 function with an API token, call it via HTTPS and include the following HTTP header in your request:

Authorization: whm username:token

Example scripts

Use the following examples to create a script that includes the API token in your custom code:

Perl

#!/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. It also 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, it parses the JSON data and returns the account's usernames.
  • If the listacct function fails, it returns an error message.

PHP

<? $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 the root 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 a curl call. It then configures the call to send the Authorization: token $user:$token headers with every request.
• Line 16 performs the WHM API 1 listaccts function via a curl call and saves the response in the $response variable.
• The script prints the following output:
  • If the listacct function succeeds, it parses the JSON data and returns the account's usernames.
  • If the listacct function fails, it returns an error message.

curl

curl -H'Authorization: whm username:MYAPITOKEN' 'https://127.0.0.1:2087/json-api/applist?api.version=1'