Development Guides Home >> Guide to Testing Custom Code

Guide to Testing Custom Code - API Authentication

Introduction

This guide explains the basics of how to test your custom code's authentication with the cPanel & WHM server.

This document lists appropriate test steps for most custom code, and helpful information to troubleshoot common problems. Make certain that you evaluate the testing requirements of your own code, and allow its functionality to determine the appropriate steps.

Testing steps

Check to ensure that you authenticated as the correct user

Many authentication issues occur because the custom code does not authenticate as a user who has the correct permissions.

Check our documentation to ensure that the function you called exists in that API and performs the desired action:

• Guide to cPanel UAPI
• Guide to WHM API 1
• Guide to cPanel API 2

Access Hash Authentication: Check to ensure that you formatted the access hash correctly

When you use an access hash or an API Token to authenticate as the root user, you must supply the hash as a single, unbroken line.

• Line breaks will cause authentication errors.
• To retrieve the server's access hash, use WHM's Remote Access Key interface ( WHM >> Home >> Clusters >> Remote Access Key ).

Single Sign-On: Check to ensure that you retrieved the required cookie

When you use Single Sign-On to authenticate, you must perform a GET request to the URL that the function returns as the url value.

• This request returns a cookie that must exist for subsequent API calls to authenticate successfully.
• For examples of how to properly store the cookie in your custom code, read our Guide to API Authentication documentation.

Troubleshoot common issues

FAILED LOGIN cpaneld: invalid cpanel user root

Problem:

You receive the following error:

FAILED LOGIN cpaneld: invalid cpanel user root

Solution:

This error occurs when you attempt to supply the root user as a cPanel user in order to call a cPanel API 2 or cPanel UAPI function. The root user can only call WHM API 1 functions, not cPanel functions. You may see similar errors if you attempt to authenticate as a reseller-level account, or as an account that does not exist on the server.

To resolve this issue, you must authenticate as a valid cPanel account.

Single Sign-On Request Failed with a Fatal Error: Client

Problem:

You receive the following error:

Single Sign-On Request Failed with a Fatal Error: Client

Solution:

This error occurs when custom code that uses the Single Sign-On method to authenticate receives an invalid user (for example, if you attempt to use Single Sign-On to authenticate as a reseller in order to run a cPanel function).

To resolve this issue, you must authenticate as a user with the correct permissions.

Missing Switch Account or Current User menu on reseller login via Single Sign-On method

Problem:

A reseller account authenticated successfully through the Single Sign-On method, but the Switch Account menu (cPanel & WHM version 56 and earlier) or Current User menu (cPanel & WHM version 58 and later) does not display as expected in the cPanel Home interface.

Solution:

Due to the way in which WHM API 1's create_user_session function creates a user session, this is intended behavior. The reseller authenticated successfully.