Manage API Tokens in WHM

Valid for versions 110 through the latest version

Version:

110

Last modified: June 13, 2024

Overview

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.

The API Tokens table

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:ss format.

• 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 or prefix 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.

• Actions

  • Edit — Edit the API token.
  • Revoke — Revoke the API token.

Create an API token

To create an API token, perform the following steps:

1. Click Generate Token. The Generate API Token interface will appear.

2. 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 (a through z and A through Z), numbers (0 through 9), dashes (-), and underscores (_).

3. 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 YYYY-MM-DD format, where YYYY is the four-digit year, MM is the month, and DD is the day of the month. The token will expire on the date you select at 11:59:59 PM, server time.
     Important:

     • When an API token expires, the system will not remove it. You must manually delete an API token.
     • You can remove an API token in this interface or use the WHM API 1 api_token_revoke function.

4. 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:

   • Single IP address (for example, 10.5.3.33 or 12AB:0:0:CD30:123:4567:89AB:CDEF).
   • CIDR or prefix format (for example, 10.5.3.0/24 or 12AB:0:0:CD30::/60).
   Note:

   To allow all IP addresses to use the API token, leave this text box blank.

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

   Warning:

   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 root user functions.
   • 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.

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

7. Click Yes, I saved my token. The new API token and its creation time will appear in the API Tokens list.

   Note:

   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:

1. Locate the API token that you want to edit in the API Tokens list.
2. Under the Actions column, click Edit. The Edit API Token interface will appear.
3. 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

To revoke an API token, perform the following steps:

1. Locate the API token that you want to revoke in the API Tokens list.
2. Under the Actions column, click Revoke. A confirmation message will appear.
3. 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:

1. Click the gear icon () and click Revoke All. A confirmation message will appear.
2. Click Continue to revoke all API tokens. A success message will appear in the upper-right corner of the interface.