An API token lets a script authenticate to cPanel without your password. It is the correct way to automate anything, and the reason it exists is that the alternative, embedding your account password in a script, is a genuinely bad idea.
Why a token instead of the password
Three differences, and each one matters when something goes wrong.
It can be revoked individually. A leaked token is one click to invalidate, and nothing else stops working. A leaked password means changing it everywhere it was used.
It can be restricted. A token can be limited to specific functions, so a script that creates email accounts cannot delete databases.
It does not grant interface access. Holding a token does not let someone log in to cPanel and look around.
Creating one
In cPanel, open Manage API Tokens and create a token.
Give it a name describing what uses it, backup-script, billing-sync: not token1. A year from now the name is the only thing telling you whether it is safe to revoke.
Set an expiry if the task is finite. A token for a one-off migration should not still be valid next year.
The token is shown once. Copy it then, because there is no way to retrieve it afterwards, only to delete it and create another.
Restrict what it can do
The step that turns a token from a convenience into a control.
cPanel lets you grant access to specific features rather than everything. A script that reads disk usage needs one function; giving it full access means a compromise of that script is a compromise of the account.
Work out what the script actually calls, grant those, and test. It takes ten minutes more than granting everything, and it is the difference between a limited incident and a total one.
Using it
The token goes in an authorisation header:
curl -H "Authorization: cpanel username:TOKEN" \ "https://example.com:2083/execute/Email/list_pops"
Port 2083 is the secure cPanel port. Use it rather than 2082, which is unencrypted. A token sent in the clear is a token someone else now has.
The response is JSON, with the result under a data key and any error reported separately. Check for the error instead of assuming a response means success.
Keep it out of your code
The mistake that undoes everything above.
A token pasted into a script is in your repository, in every clone of it, and in the history even after you remove it. A token in a shell command is in your shell history.
Put it in an environment variable, or a configuration file outside the web root with permissions of 600. Read it at run time.
And keep that file above public_html. A configuration file inside the web root can be downloaded by anyone who guesses the name. Understanding file permissions deals with why placement matters more than permissions here.
What it can and cannot reach
A cPanel token acts as your account. It can do what you can do in cPanel: email accounts, databases, subdomains, files, cron jobs, DNS records for your own domains.
It cannot do server-level things. Creating accounts, changing packages and anything else in WHM needs a WHM token instead, which is a separate credential with far greater reach. Using the WHM API walks through that side.
Do not use a WHM token where a cPanel token would do. The blast radius is not comparable.
Common uses that are worth automating
Creating email accounts when a customer signs up, so nobody does it by hand.
Reading disk and bandwidth usage into your own dashboard, which is more useful than logging in to check.
Adding DNS records as part of a deployment.
Triggering a backup before a deployment runs.
Each of those is a script that would otherwise be a person, and each is a good reason to have a token scoped to exactly that job.
Review them periodically
The list of tokens is visible in the same screen that creates them. Look at it a couple of times a year.
Delete tokens for things you no longer run. A forgotten token is a working credential nobody is watching, and it will outlive the script it was made for.
If you cannot tell what a token is for, that is itself the answer: revoke it and see what breaks. Anything still needed announces itself within a day, and everything else was dead weight.
If one is exposed
Revoke it immediately. That is the whole point of the design, and it takes one click.
Then create a replacement, update whatever used it, and check what happened while it was valid: new email accounts, new cron jobs, changed DNS records, files that appeared.
A token cannot log in to the interface, which limits the damage. It can still create a cron job that does anything your account can do, and that survives the token being revoked. Setting up cron jobs goes into where to look.
Test the token before building on it
A token that does not work produces the same response as a request that is malformed, so confirming it separately saves a lot of guessing.
curl -sH 'Authorization: cpanel username:TOKEN' \
'https://example.com:2083/execute/Email/list_pops' | head -c 300
echo
curl -s -o /dev/null -w '%{http_code}\n' -H 'Authorization: cpanel username:TOKEN' \
'https://example.com:2083/execute/StatsBar/get_stats?display=diskusage'
A response containing data means the token, the username and the address are all correct. An authentication failure with a valid looking token is usually the username, since the token belongs to one account and is meaningless against another.
Read the returned structure as well. Errors are frequently reported inside a successful response rather than as a failed status, which means checking only the status code hides them.
Give each integration its own
One token used by three things cannot be revoked for one of them, which is how a token that should be replaced stays in place for years.
Issue one per system, named after the system rather than after the person who created it. When something changes, only the affected integration is disrupted, and the name says immediately what will stop working.
The same applies to privileges. A token used for reading statistics does not need permission to create accounts, and giving it that permission means an exposure of a monitoring credential becomes an exposure of the account.
Watch for the token that is no longer used
Tokens do not expire, so the list only grows and the entries stop corresponding to anything.
curl -sH 'Authorization: cpanel username:TOKEN' \ 'https://example.com:2083/execute/Tokens/list_tokens' | head -c 400 echo grep -c 'Authorization: cpanel' ~/logs/example.com 2>/dev/null
Read the list against what you are actually running. Anything you cannot attribute to a live system should be removed, and removing it is safe in the sense that the failure is immediate and obvious rather than silent.
An unused token is not harmless. It is a working credential held wherever it was pasted, in a script, a configuration file, or somebody's notes, with nobody watching whether it is being used. Securing your hosting account covers the wider review.