Cloudflare API 403 Forbidden: Find the Missing Token Permission and Fix It

A Cloudflare API request can authenticate successfully and still return HTTP 403. That usually means the token exists, but it is not authorized for the requested endpoint or resource.

Start by preserving the complete response:

curl -sS -D headers.txt \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records"

Cloudflare's newer 403 responses may include a documentation_url pointing to the denied endpoint's documentation. Use that URL to confirm the required permission instead of guessing from the endpoint name.

1. Verify the Header Format

API tokens use a Bearer header:

Authorization: Bearer <API_TOKEN>

The older Global API Key flow uses different headers. Mixing the two authentication methods causes misleading failures. Prefer scoped API tokens over the Global API Key.

2. Confirm the Required Permission

Reading DNS records typically requires a DNS read permission; modifying them requires DNS edit. A token with Zone Read is not automatically allowed to edit DNS.

Check both dimensions in the token configuration:

• Permission group: What operation is allowed?
• Resource scope: Which account, zone, or resource is covered?

A correctly permissioned token for example.com will still receive 403 when used with another zone ID.

3. Check Account ID vs Zone ID

Cloudflare endpoints are commonly scoped under either:

/accounts/{account_id}/...
/zones/{zone_id}/...

Passing an account ID where a zone ID is expected can look like an authorization problem. Retrieve the target identifier first and log which identifier your automation selected.

4. Test the Token Separately

Use Cloudflare's token verification endpoint before debugging the application:

curl -sS \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  https://api.cloudflare.com/client/v4/user/tokens/verify

An active token proves that authentication works. It does not prove that the token can access the requested zone or endpoint.

5. Reproduce with the Smallest Request

Remove SDKs, Terraform providers, and CI wrappers temporarily. Reproduce the request with curl, the exact resource ID, and the same token. If curl works, inspect how the application reads and passes its secret. Common causes include a trailing newline, an environment variable unavailable in the job, or a secret shadowed by an empty variable.

6. Do Not Fix It with an Overpowered Token

Giving the token every permission may remove the error, but it also hides the root cause and increases blast radius. Add only the permission identified by the endpoint documentation and restrict it to the required account or zone.

For CI, create separate tokens for separate workflows. A DNS deployment should not share credentials with Workers deployment or account administration.

Quick Diagnostic Checklist

[ ] Bearer header is being used for an API token
[ ] Token is active
[ ] Required read/edit permission is present
[ ] Correct account or zone is included in resource scope
[ ] Account ID and zone ID are not swapped
[ ] CI receives the non-empty secret
[ ] documentation_url matches the endpoint being called

Most Cloudflare API 403 errors are not outages. They are precise authorization failures obscured by a token that appears valid. Diagnose permission and resource scope independently, then make the smallest safe change.

Sources

• Cloudflare API documentation
• Cloudflare developer changelog