Skip to content

feat: support Cloudflare Global API Key authentication#34

Open
tjuranek wants to merge 2 commits intocloudflare:mainfrom
tjuranek:feat/global-api-key-auth
Open

feat: support Cloudflare Global API Key authentication#34
tjuranek wants to merge 2 commits intocloudflare:mainfrom
tjuranek:feat/global-api-key-auth

Conversation

@tjuranek
Copy link

Summary

  • Adds support for authenticating with Cloudflare's Global API Key via X-Auth-Email + X-Auth-Key headers, alongside the existing OAuth and Bearer token methods
  • Global API Key credentials flow through GlobalOutbound props — same isolation pattern as Bearer tokens (fix: move API token injection to GlobalOutbound via props #28), never entering the dynamic worker isolate
  • getUserAndAccounts is generalized to accept either auth style (backward-compatible, still accepts a plain string)
  • OutboundAuth discriminated union replaces the raw apiToken: string plumbing through the executor and server, so GlobalOutbound injects the correct headers (Authorization: Bearer vs X-Auth-Email/X-Auth-Key)
  • README updated with Option 3 documenting the Global API Key config, with a warning that it grants full account access

Files changed

File Change
src/auth/types.ts Add global_api_key variant to AuthProps union
src/auth/oauth-handler.ts Add buildCloudflareAuthHeaders, generalize getUserAndAccounts
src/auth/api-token-mode.ts Add isGlobalApiKey detection + handleGlobalApiKeyRequest handler
src/index.ts Update GlobalOutbound props to support both auth types, wire up Global API Key check
src/executor.ts Replace apiToken: string with OutboundAuth union
src/server.ts Add getOutboundAuth helper, pass OutboundAuth to executor
README.md Add Option 3: Global API Key section

Test plan

  • isGlobalApiKey correctly detects X-Auth-Email + X-Auth-Key headers (5 test cases)
  • buildCloudflareAuthHeaders returns correct headers for both auth types (2 test cases)
  • Existing isDirectApiToken, extractBearerToken, buildAuthProps tests still pass (unchanged)
  • Executor tests updated to use OutboundAuth type instead of raw string
  • Tested locally with wrangler dev — Global API Key request successfully authenticates, tools/list returns both tools, execute tool runs code against the Cloudflare API
  • Bearer token and OAuth paths unaffected (no breaking changes)
  • All 76 tests pass, npm run check clean (format, lint, typecheck, test)

🤖 Generated with Claude Code

tjuranek and others added 2 commits February 20, 2026 16:54
Add support for authenticating with Cloudflare's Global API Key
(X-Auth-Email + X-Auth-Key headers) alongside the existing OAuth and
Bearer token methods. This enables users who prefer the legacy Global
API Key to use the MCP server without needing to create scoped API
tokens.

- Add `global_api_key` variant to AuthProps discriminated union
- Detect X-Auth-Email + X-Auth-Key headers in incoming requests
- Generalize getUserAndAccounts to accept either Bearer or Global API
  Key credentials
- Update GlobalOutbound to inject the correct auth headers based on
  auth type (Bearer vs X-Auth-Email/X-Auth-Key)
- Refactor executor and server to pass OutboundAuth instead of raw
  token strings
- Add tests for isGlobalApiKey detection
- Update executor tests to use OutboundAuth type

Co-Authored-By: Claude Opus 4.6 <[email protected]>
@tjuranek
Copy link
Author

Hey — I know this is an AI-assisted PR so I want to be upfront about that, but the motivation is
very real: I've been using the MCP server and kept hitting permission issues with scoped API
tokens. Getting the right combination of permissions configured for everything I want to do through
the agent is painful, and the Global API Key just works out of the box.

I realize it's a tradeoff — the Global API Key is less secure since it grants full account access —
but until there's an easier way to configure broad permissions on scoped tokens, I think it's a
useful option to have alongside the existing methods. The README warns about the risk.

Happy to make any changes needed to get this mergeable. Let me know if there's anything you'd want
done differently.

@mattzcarey
Copy link
Contributor

Why cant you use user or account api tokens?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants