AI Gateway: an Anthropic key in Authorization: Bearer isn't recognised as provider credentials (only x-api-key is) #34593

Existing documentation URL(s)

• https://developers.cloudflare.com/ai-gateway/features/unified-billing/ (section "Credential precedence")
• https://developers.cloudflare.com/ai-gateway/reference/troubleshooting/
• https://developers.cloudflare.com/ai-gateway/usage/providers/anthropic/

What changes are you suggesting?

On the provider-specific Anthropic endpoint, AI Gateway doesn't treat an Anthropic key sent in Authorization: Bearer as provider credentials. It only does so for x-api-key. Two pages suggest otherwise, so we built against Authorization and found out only from a live request.

What the docs say:

• Unified Billing, "Credential precedence", step 1: "Provider key on the request — if the request carries provider authentication (for example, an Authorization header), AI Gateway forwards it to the provider unchanged. BYOK and Unified Billing are not consulted."
• Troubleshooting: "Make sure your Cloudflare token is in cf-aig-authorization, not Authorization. The Authorization header is reserved for provider credentials."

Anthropic's own API accepts a key as Authorization: Bearer <key>, so we read these sentences as covering it.

What we observed on 2026-10-24. These were two requests to POST https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic/v1/messages on a new gateway with Authenticated Gateway and Require provider credentials turned on. Both had the same body, a minimal Messages request to claude-haiku-5-5. Both had the same other headers: cf-aig-authorization: Bearer <gateway token>, anthropic-version: 2026-10-21, content-type: application/json, cf-aig-collect-log-payload: false, cf-aig-skip-cache: true and cf-aig-no-wholesale: true.

1. With the Anthropic key in Authorization: Bearer <anthropic key>, the gateway returned HTTP 400 with this body:

   {"error":[{"code":2044,"message":"Customer-provided provider credentials are required for this request"}]}

   The response had cf-aig-step: 0, and the gateway's log shows the request as failed, with no tokens.
2. With the same key in x-api-key: <anthropic key> instead, it returned HTTP 200 from claude-haiku-5-5.

So for this endpoint, Authorization isn't recognised as "provider authentication", and only x-api-key is. The Anthropic provider page's cURL examples do use x-api-key, but nothing on that page says that Authorization won't work.

Why it matters. We only saw the 400 because Require provider credentials was on, and because we sent cf-aig-no-wholesale: true. By the precedence rules, a request without recognised provider credentials goes on to BYOK and then Unified Billing. So with that setting off, we'd expect such a request to be served with Cloudflare-managed credentials and billed to the Cloudflare credit balance, while the developer believes it's using their own key. We haven't tested that case. The expectation is our reading of the precedence rules.

Suggested changes:

• In "Credential precedence", say which headers count as provider authentication for each provider. For Anthropic, that's x-api-key, and Authorization: Bearer is not recognised, if that's intended.
• Qualify the Troubleshooting sentence, or link it to that list.
• On the Anthropic provider page, say that the key must be sent in x-api-key.
• Document error code 2044, perhaps on the Troubleshooting page, so that it can be found.

Additional information

The gateway's log entry for each request is available, if useful: the 400 had cf-aig-log-id: 01a16fd7-4a9c-7337-9e35-d33a029a0e6f, and the 200 had cf-aig-log-id: 01a16fd7-9de7-701b-a89a-964e47d078a8. We found this while adding AI Gateway to Haystack, in schalkneethling/haystack#156.