Managing API tokens in WHM allows you to create secure authentication credentials for remote API access without sharing your root password. You can create, list, update, and revoke API tokens while assigning specific Access Control List (ACL) privileges to control what each token can access. This feature is essential for granting resellers or third-party developers limited access to WHM's API functions safely.
What Are API Tokens in WHM?
API tokens are secure authentication credentials that replace traditional username and password combinations when accessing WHM's remote API. Instead of sharing your account password, you generate a unique token with specific permissions that can be revoked at any time without changing your main credentials.
At OBHost, API tokens provide an additional security layer by limiting what actions can be performed through the API. Each token can have its own set of permissions, making it ideal for granting access to automated scripts, third-party applications, or reseller accounts.
Current Limitations and Important Considerations
Before creating API tokens, you should understand several important limitations:
- The ACL restriction feature for API tokens is currently experimental and may change in future WHM versions
- API tokens currently work only with WHM API functions, DNS clusters, and configuration clusters
- You cannot create API tokens for suspended accounts
- If you change a cPanel account username, existing API tokens will continue to function
- Deleting a cPanel account automatically revokes all associated API tokens
Note: To remove an account's API token access, you must manually revoke the token through the API Tokens interface.
How to Access the API Tokens Interface
The API Tokens interface is available in WHM's management area. To access it, navigate through your WHM dashboard to the API token management section. This interface will only appear if all initial privileges are enabled in the Edit Reseller Nameservers and Privileges section for reseller accounts.
Creating a New API Token
When creating a new API token, you'll need to provide several key details:
- A descriptive name that helps you identify the token's purpose
- An optional expiration date for enhanced security
- Specific ACL permissions that control what the token can access
After creation, the system displays your token only once. You must copy and store it securely immediately, as you cannot retrieve the full token value later.
Understanding the API Tokens Table
The API Tokens table displays all your active tokens with the following information:
- Name: The descriptive name you assigned to the token
- Created: The timestamp when the token was generated
- Expires: The expiration date if you set one, or "Never" for tokens without expiration
- Actions: Quick access buttons for managing individual tokens
Managing Existing API Tokens
The interface provides several tools for managing your tokens efficiently:
- Use the search box to filter tokens by name as you type
- Click the refresh button to update the token list with the latest information
- View detailed information about each token by clicking its name
- Modify token permissions through the edit function
- Revoke tokens immediately when they're no longer needed
Best Practices for API Token Security
Follow these security recommendations when working with API tokens:
- Create tokens with the minimum required permissions for their intended purpose
- Set expiration dates for tokens used in temporary projects or testing
- Use descriptive names that clearly indicate each token's purpose and where it's used
- Regularly audit your active tokens and revoke any that are no longer necessary
- Never share tokens through unsecured channels like email or chat
- Store tokens in secure password managers or encrypted configuration files
- Immediately revoke any token you suspect has been compromised
Revoking API Tokens
When you no longer need a token or suspect it has been compromised, revoke it immediately. Revoked tokens become invalid instantly and cannot be restored. If you need access again, you must create a new token. This ensures that any systems or scripts using the old token will immediately lose access, preventing potential security issues.
Troubleshooting Common API Token Issues
If you encounter problems with API tokens, check these common issues:
- Verify the token hasn't expired by checking the expiration date in the table
- Confirm the token has the necessary ACL permissions for the API functions you're calling
- Ensure you're using the complete token string without any extra spaces or characters
- Check that the associated account isn't suspended
- Verify your API calls are correctly formatted and using supported endpoints
Frequently Asked Questions
Can I use API tokens with cPanel API functions?
Currently, API tokens work exclusively with WHM API functions, DNS clusters, and configuration clusters. They are not supported for cPanel API functions at this time. This limitation is documented in the WHM interface and may change in future versions.
What happens to API tokens when I change an account username?
API tokens remain active and continue functioning even after you change an account's username in WHM's Modify an Account interface. The tokens are tied to the account itself, not the username. To disable access, you must manually revoke the tokens.
How do I know if my API token has the right permissions?
You can view and modify token permissions through the API Tokens interface. Click on a token name to see its current ACL settings. If your API calls are failing with permission errors, you'll need to edit the token to grant additional privileges for the specific functions you're trying to access.
Can I recover a token after I revoke it?
No, once you revoke an API token, it becomes permanently invalid and cannot be restored. If you need to provide access again, you must create a new token with the appropriate permissions. This security measure ensures that revoked tokens cannot be reactivated even if they were previously compromised.
OBHost's support team is available 24/7 to help with API token management and WHM configuration. If you need assistance setting up tokens or troubleshooting API access, visit https://www.obhost.net/contact or email support@obhost.org.
