Manage API Tokens in WHM
Valid for versions 98 through the latest version
Last modified: July 28, 2022
This interface lets you to create, list, update, and revoke API tokens. It also lets you assign Access Control List (ACL) privileges to API tokens. You can use an API token to authenticate with WHM’s remote API. This is useful, for example, to allow a reseller or third-party developer to run API function calls with your account’s data.
- If you change a cPanel account’s username in WHM’s Modify an Account interface (WHM >> Home >> Accounts >> Modify an Account) any API tokens the account uses will continue to function. To remove an account’s API token, you must revoke the API token.
- If you delete a cPanel account, the system will revoke the account’s API tokens.
- You cannot create an API token for a suspended account.
The API Tokens table
This section of the interface only appears if all of the Initial Privileges are enabled in WHM’s Edit Reseller Nameservers and Privileges interface (WHM >> Home >> Resellers >> Edit Reseller Nameservers and Privileges).
This section of the interface displays all of your API tokens. You can also perform the following actions:
- To search for an API token, enter a term in the Search text box. The interface automatically filters the API token names as you type.
- To refresh the API tokens list, click the gear icon () next to the Actions column heading and click Refresh List.
The API tokens table displays the following:
Name — The API token’s name.
Created — The time that you created the API token, in
MM DD YYYY hh:mm:ssformat.
Expires — If an API token expires, the date and time at which the token will expire.
When an API token will soon expire, the interface displays its entry row in yellow. It also displays a notice icon ().
The interface displays expired API token entry rows in red. It also displays a notice icon ().Note:
When API tokens expire, the system does not remove them. You must manually delete expired API tokens.
IPs — The IP address or IP address range (in CIDR format) of the API caller that can use the token. If the column contains Any, any address can use the token.Note:This feature allows a maximum of 100 IP addresses and/or IP address range entries.
Create an API token
To create an API token, perform the following steps:
Click Generate Token. The Generate API Token interface will appear.
Enter a unique name for the API token in the Name text box.Note:
- An API token name can only contain up to 50 characters.
- You can only enter letters (
Z), numbers (
9), dashes (
-), and underscores (
Select one of the following settings from the Should the API Token Expire? section:
The API Token will not expire. — This will create a token that does not have an expiration date.
Specify an expiration date. — This allows you to create a token that expires on a specific date. By default, tokens expire one year from the current date. When you select this setting, the interface displays the API Token Expiration Date section. Use the the calendar icon () to open a calendar to select a desired expiration date. You can also enter a custom date in the calendar text box. Use the
YYYYis the four-digit year,
MMis the month, and
DDis the day of the month. The token will expire on the date you select at
11:59:59 PM, server time.
In the IPs text box, enter the IP addresses of devices that can use this API token. You can enter IP addresses in any of the following formats:
Note:This setting defaults to allowing all IP addresses to use the WHM API token.
Single IP address (for example,
CIDR format (for example,
In the Privileges section, deselect the checkbox for ACL privileges that you do not want to give to the token. For more information, read our Edit Reseller Nameservers and Privileges documentation.Note:
You must assign at least one ACL privilege to the token.
Only ACL privileges that the user possesses will appear in this section.
Use caution when you assign the following ACL privileges:
Everything — This allows an API token user access to the entire system. A user with this token can perform all
Change Password — This will allow an API token user to change account passwords and log in with a new password.
Create User Session and Manage API Tokens — These will allow an API token user to bypass any restrictions that you set on the API token.
Click Generate. The new API token hash and its name will appear. The interface also displays the date on which the API token will expire.Warning:
Make certain that you save your API token in a safe location on your workstation. You cannot access the token after you navigate away from the interface or refresh the API Tokens table.
Click Yes, I saved my token. The new API token and its creation time will appear in the API Tokens list.
For information about how to use the API token with API calls, read our Guide to API Authentication - API Tokens in WHM documentation.
Edit an API token
To edit an API token, perform the following steps:
Locate the API token that you want to edit in the API Tokens list.
Under the Actions column, click Edit. The Edit API Token interface will appear.
Edit the desired settings, then click Save. A success message will appear in the upper-right corner of the interface.Remember:
You must assign at least one ACL privilege to the token.
Revoke an API token
If you revoke an API token, any script or account using the API token will not function.
To revoke an API token, perform the following steps:
Locate the API token that you want to revoke in the API Tokens list.
Under the Actions column, click Revoke. A confirmation message will appear.
Click Continue to revoke the token. A success message will appear in the upper-right corner of the interface.
To revoke all API tokens, perform the following steps:
Click the gear icon () and click Revoke All. A confirmation message will appear.
Click Continue to revoke all API tokens. A success message will appear in the upper-right corner of the interface.