Managing API tokens in cPanel allows you to securely automate tasks and integrate third-party applications without exposing your login credentials. API tokens enable you to run cPanel functions programmatically, making it easy to check disk usage, manage domains, or perform other account operations without logging into the cPanel interface.
What Are cPanel API Tokens?
API tokens are secure authentication credentials that allow you to access cPanel API functions without using your account password. When you create an API token, you can grant specific permissions or limit its scope, making it safer than sharing your password with applications or developers. For example, you might create a token that only allows checking disk usage statistics, while blocking access to email or domain management functions.
These tokens work with UAPI and cPanel API 2 functions, giving you programmatic access to most cPanel features. At OBHost, API tokens are an excellent way to automate routine tasks or integrate your hosting account with external monitoring tools and applications.
Creating a New API Token
To create an API token in your cPanel account, follow these steps:
- Log into your cPanel account and navigate to the Manage API Tokens section under Security.
- Click the Create button to open the token creation interface.
- Enter a descriptive name in the API Token Name field. Choose a name that helps you remember what the token is used for, such as "Backup Script" or "Monitoring Tool".
- Choose an expiration option for your token. You can either set it to never expire or specify an expiration date for added security.
- Click Create to generate your token.
- Copy the token immediately and store it securely. You will only see the complete token once during creation.
Important naming requirements:
- Token names can contain up to 50 characters
- Only letters (a-z, A-Z), numbers (0-9), dashes (-), and underscores (_) are allowed
- Each token name must be unique within your account
Setting Token Expiration Dates
When creating an API token, you have two expiration options:
No Expiration: The token remains valid until you manually revoke it. This option is convenient for long-term integrations but requires careful security management.
Specific Expiration Date: The token automatically expires on the date you specify. By default, cPanel suggests an expiration date one year from creation. This option is more secure for temporary access or when granting tokens to third parties.
Setting expiration dates is a best practice for security. Even if a token is compromised, it will automatically become invalid after the expiration date, limiting potential damage.
Managing and Revoking Existing Tokens
The Manage API Tokens interface displays all your active tokens in a list format. For each token, you can see its name, creation date, expiration date (if applicable), and last use timestamp.
To revoke an API token:
- Locate the token you want to remove in the token list.
- Click the Revoke button next to the token.
- Confirm the revocation when prompted.
Once revoked, the token immediately stops working. Any applications or scripts using that token will no longer be able to access your cPanel account. Make sure to update any integrations before revoking a token that is actively in use.
Using API Tokens Securely
API tokens are powerful tools that require careful handling. Follow these security best practices:
- Store tokens securely: Never commit tokens to public repositories or share them in plain text. Use environment variables or secure credential management systems.
- Create specific tokens for each use case: Instead of using one token for everything, create separate tokens for different applications or scripts. This makes it easier to revoke access if needed.
- Set expiration dates: Use expiring tokens whenever possible, especially for temporary access or testing.
- Review tokens regularly: Periodically check your token list and revoke any tokens that are no longer needed.
- Monitor token usage: Check the last use timestamp to identify tokens that may have been compromised or are no longer needed.
API Token Limitations and Important Notes
Keep these important points in mind when working with cPanel API tokens:
The API token feature is considered experimental and may change in future cPanel versions. While it is stable and widely used, always test your implementations after major cPanel updates.
Unrestricted API tokens can access API functions that do not have associated feature restrictions. This means tokens can potentially access more functionality than you might expect, so always review the permissions carefully.
API tokens work with UAPI and cPanel API 2 functions, but they do not support cPanel API 1 functions. If you are working with legacy code that uses API 1, you will need to update it to use the newer API versions or continue using password-based authentication for those specific calls.
Practical Use Cases for API Tokens
API tokens enable many useful automation scenarios:
Automated Backups: Create a token for backup scripts that run on a schedule, allowing them to download files or database exports without manual intervention.
Monitoring and Alerts: Grant tokens to monitoring services that check your disk usage, bandwidth consumption, or uptime without needing your password.
Third-Party Integrations: Connect your hosting account with project management tools, customer portals, or custom applications that need to read or update account information.
Development and Testing: Issue temporary tokens to developers working on integrations, then revoke them when the project is complete.
What happens if my API token expires?
When an API token reaches its expiration date, it immediately stops working. Any applications or scripts using that token will receive authentication errors. You will need to create a new token and update your applications with the new credentials. There is no way to extend or renew an expired token.
Can I see the full token value after creation?
No, the complete token value is only displayed once during creation. After you close the creation dialog, you can only see the token's name and metadata in the management interface. If you lose a token, you must revoke it and create a new one.
How many API tokens can I create?
There is no strict limit on the number of API tokens you can create in cPanel. However, for security and management purposes, it is best to create only the tokens you actually need and revoke unused ones regularly.
What is the difference between restricted and unrestricted tokens?
Unrestricted API tokens can access any UAPI or cPanel API 2 function available to your account, including functions that do not have specific feature restrictions. This provides maximum flexibility but requires careful security management. Always use unrestricted tokens only when necessary and consider the security implications of granting broad access.
If you need help managing API tokens or have questions about securing your cPanel account at OBHost, our support team is available 24/7. Visit our contact page or email support@obhost.org for assistance.
