Credentials and account context

Create an API token in the Cloudflare dashboard with only the permissions and account or zone access your script needs. Cloudflare offers user tokens and account tokens; the endpoint and your account permissions determine which is appropriate. Copy the token when it is created and keep it in your normal secret store. The Cloudflare token guide explains the dashboard steps and permission scoping.

# Load CLOUDFLARE_API_TOKEN from your secret manager first.
export CLOUDFLARE_ACCOUNT_ID='your-account-id'
cloudflare-api --resource r2 --action list_buckets

The account ID above is a placeholder. Load the token through your secret manager so it does not enter a repository or a pasted command. The module also accepts explicit token and account_id constructor options:

my $api_or=Cloudflare::API->new(
    token      => $ENV{'CLOUDFLARE_API_TOKEN'},
    account_id => $ENV{'CLOUDFLARE_ACCOUNT_ID'},
    timeout    => 30
);

You can omit account_id for account and zone lookup, but account-scoped methods need it. The command has --account-id to choose another account while continuing to read the token from the environment.

Warning

An API token is a credential, even when it is short lived. Do not commit it, paste it into command-line arguments, print it in logs, or include it in error reports. Use a narrowly scoped token; a token that can edit a resource can change or delete it through the relevant methods.

If you have logged into Wrangler locally, the command can ask Wrangler for a token for each invocation. Wrangler refreshes an expired OAuth token before returning it:

cloudflare-api --auth=wrangler --resource workers --action list_scripts

For an account-scoped named method, --auth=wrangler also uses wrangler whoami --json to obtain the account ID when the login has exactly one available account. If it has several, select one with --account-id or CLOUDFLARE_ACCOUNT_ID; either value takes precedence and skips account discovery. Run wrangler login separately if you have not logged in. Wrangler returns an existing CLOUDFLARE_API_TOKEN in preference to its OAuth login; it does not mint a newly scoped API token. API key and email credentials are not supported by --auth=wrangler. When you rely on a Wrangler login, the returned OAuth token has the permissions of that login. The module does not refresh a token passed to its constructor; the command asks Wrangler again on each invocation. See the Wrangler auth token reference for the current command behaviour.

Tip

For unattended scripts, use a dedicated, limited API token supplied by a secret manager. The Wrangler shortcut is best suited to an interactive session you control.