Child pages
  • Guide to Testing Custom Code - API Authentication

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Excerpt
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. 

Multiexcerpt include
MultiExcerptNameUnsupported
PageWithExcerptGuide to Testing Custom Code

Testing steps


Note
titleNote:

Because the testing requirements of custom code differ, this document begins with the assumption that you already discovered problems. 


Section


Column
width72px


Column

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.

Warning
titleImportant:
  • cPanel users can only call cPanel API 1, cPanel API 2, and UAPI functions, and in many cases must have access to the correct features for those functions.
  • WHM users can call cPanel API 1, cPanel API 2, and UAPI functions, but you must specify a cPanel user to call those functions as. 

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


 


 

Section


Column
width72px


Column

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

Warning
titleWarning:

Include Page
LIB:_RemoteAccessKeyDeprecated
LIB:_RemoteAccessKeyDeprecated

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).


 


 

Section


Column
width72px


Column

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.


 


 

Section


Column
width72px


Column

Anchor
Troubleshoot
Troubleshoot
Troubleshoot common issues

FAILED LOGIN cpaneld: invalid cpanel user root


Section


Column
width10%

Problem:


Column

You receive the following error:

Code Block
languagetext
FAILED LOGIN cpaneld: invalid cpanel user root




Section


Column
width10%

Solution:


Column

This error occurs when you attempt to supply the root user as a cPanel user, generally in order to call a cPanel API 1, cPanel API 2, or UAPI function. The root user can only call WHM API 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


Section


Column
width10%

Problem:


Column

You receive the following error:

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




Section


Column
width10%

Solution:


Column

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


Section


Column
width10%

Problem:


Column

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.



Section


Column
width10%

Solution:


Column

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.