My API token works everywhere except Redirect Rules

By Idea to Traffic Editorial Team · Published September 27, 2026 · Last updated September 27, 2026

A token that worked for everything but one call

We POSTed a straightforward www to apex 301 to the zone rulesets endpoint and got back error code 10000, described only as an authentication error. No field name, no scope name, no hint about which permission was involved.

The token was not suspect, which is what made this expensive. Minutes earlier the same token had created a Pages project, attached a custom domain, written DNS records, enabled Email Routing, created a D1 database and changed zone settings. It worked for nine things and failed for one, and a token that behaves that way looks like a broken endpoint rather than a missing permission. We went looking at request bodies, ruleset phases and API versions before we looked at the token.

Cache Purge on the same token failed identically, with the same 10000 and the same empty description. Two unrelated-looking endpoints failing the same way was the clue we should have read first. Diagnosing it cost .

Rulesets is its own permission

Cloudflare API tokens are scoped by permission group, and the permission groups do not line up with how people mentally group products. Redirect Rules are implemented as rulesets, so they sit behind the Rulesets permission. Cache Purge is its own separate permission group. Neither is implied by having Pages, DNS or zone settings access.

Error 10000 is Cloudflare's generic authentication error, and it is reused for the case where a token is entirely valid but lacks the specific permission the endpoint requires. That reuse is the whole problem. A revoked token, a malformed header and a correctly authenticated token missing one permission group all produce the same response, so the error text can never tell you which of the three you have.

There is one more wrinkle worth knowing before you conclude anything. New token permissions take 30 to 60 seconds to reach the edge. A 10000 immediately after changing a permission may simply be propagation, and retrying too quickly and then concluding the permission did not help is a common way to end up back at the wrong hypothesis.

Reading the token's permission list

Use a timing rule rather than a guess. A transient 10000 in the first minute after a permission change is propagation. A persistent 10000 on the same endpoint after a minute has passed is a missing permission.

Next, separate a bad token from a scoped-out token by seeing how wide the failure is. Call something in a different permission group that you know the token holds, then call the failing endpoint again.

curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  "https://api.cloudflare.com/client/v4/zones/<zone_id>/dns_records?per_page=1"

curl -s -X GET -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  "https://api.cloudflare.com/client/v4/zones/<zone_id>/rulesets"

If the first call returns results and the second returns 10000, the token is live and the gap is scope. If both fail, the token itself is the problem. A token verify call will tell you the token is active and will say nothing at all about which permissions it carries, so it confirms the first case and never diagnoses the second.

The last confirmation is the cheapest one available. Read the token's permission list and check it against the endpoint you are calling, looking specifically for Rulesets and, if purge is also failing, for Cache Purge. When a Cloudflare API call fails with 10000, check the token's permission list against the specific endpoint before you check anything else, because the error text will never volunteer it.

Add the scope, or use the dashboard

1. Retry the exact failing call once after a full minute has elapsed, to rule out permission propagation before you change anything.
2. Read the token's permission list. If Rulesets is absent, that is the answer, and the request body you have been rewriting was never the problem.
3. If you can edit the token, add the Rulesets permission, wait 30 to 60 seconds for it to reach the edge, and retry. Add Cache Purge in the same change if purge calls are failing too, because it is a separate group.
4. If the permission is not available to you and you only need the redirect, do it in Pages middleware instead. A functions/_middleware.js that 301s www to the apex achieves the same result and needs no token scope at all. This is what we did on one site in the network once Zone Redirect Rules turned out to be unavailable.

   export async function onRequest(context) {
     const url = new URL(context.request.url);
     if (url.hostname.startsWith("www.")) {
       url.hostname = url.hostname.slice(4);
       return Response.redirect(url.toString(), 301);
     }
     return context.next();
   }

5. If you need the rule once and have dashboard access, create it there. The dashboard route under Rules needs no token at all and takes about thirty seconds, which beats any amount of API archaeology for a one-off.
6. For a cache purge you cannot perform, switch the zone's Development Mode on. It bypasses cache for three hours and then expires by itself, so it needs no cleanup and no purge permission.
7. Record which permission was missing next to the endpoint that needed it, so the next person reads a note instead of repeating the investigation.

Scope tokens per endpoint, and write it down

Build tokens from a written list of permission groups matched to the endpoints your automation actually calls. Choosing scopes by product intuition is what produces a token that covers nine things and misses one. Our provisioning pipeline touches permission groups, and that count belongs in the runbook next to the token.

When you add a new API call to a pipeline, add its permission group in the same change. The cost of noticing later is not the permission edit, it is the hour spent debugging a request body that was always correct.

Keep a preflight step that calls one harmless read endpoint per permission group the pipeline needs, and fail loudly with the group name when one comes back 10000. That converts a generic authentication error into a sentence naming the scope, which is the information the API declines to give you.

Write the 30 to 60 second propagation window into the runbook, so nobody concludes a permission change did not work after ten seconds and reverts it.

Where a middleware redirect falls short

A middleware redirect is not a zone-level rule. It only applies to requests that reach that Pages project, so a hostname that is not attached to the project still will not redirect, and a rule you wanted applied across a whole zone needs the real Redirect Rule.

Development Mode is not a purge. It bypasses cache for three hours and then the previous behaviour returns, it evicts nothing, and it cannot target a single URL. Treat it as a way to keep working, not as a substitute for the purge permission.

Adding Rulesets does not repair a genuinely expired or revoked token, an account-scoped call made with a zone-scoped token, or a token restricted to source IP addresses and called from somewhere else. All three of those also return 10000 and none of them are fixed by a permission.

The general rule transfers but the specific answer does not. A 10000 on some other endpoint means go and check that endpoint's own permission group, and the missing group will frequently not be Rulesets.

None of this validates the redirect itself. A rule can be created successfully and still point the wrong way, produce a redirect chain, or strip a query string, and the API will report all of that as a success.

Questions about Cloudflare error 10000