Skip to content

CloudflareWorkers, caching and APIreference

Worker-to-Worker authentication with ES256 JWTs on Cloudflare

Authenticating Workers calling other Workers across Cloudflare accounts without a shared secret, a per-request API charge, or an external control plane. The receiver holds the public keys and assigns identity - the sender cannot self-assert who it is.

Provenance: the design-property claims in this doc - the 520 on orange-clouded mTLS, the 13-step verifier, the JTI Durable Object consistency - are cross-checked against the implementation in worker-mtls-jose but not against a multi-colo measurement run. The comparison-table properties for AWS IAM, SPIFFE and Istio are documented architecture, not a measurement from this rig.

TL;DR:

  • Cloudflare mTLS certificate bindings return 520 when the destination Worker sits behind an orange-clouded (proxied) zone, leaving no built-in mechanism for authenticated Worker-to-Worker calls1
  • Access service tokens work but couple you to the Zero Trust control plane
  • ES256 JWTs with a receiver-owned key registry give you authenticated calls without vendor lock-in, access charges or a shared secret
  • The CF-Worker header Cloudflare adds to Worker subrequests is a useful signal but spoofable - identity comes from the JWT signature, not the header2
  • Durable Object-backed JTI storage gives strongly consistent replay protection with no eventual-consistency gap

Cloudflare offers mTLS certificate bindings (mtls_certificate) for Workers to present a client certificate to an origin. When the target is an orange-clouded (proxied) zone, the connection returns 520, the catch-all origin-unreachable status1. The bindings work for grey-clouded (DNS-only) origins but that gives up the CDN - caching, DDoS protection and the Workers runtime are all behind the proxy.

Access service tokens (Cloudflare Zero Trust) authenticate Workers but introduce a dependency on the Access control plane and a per-token management model. For a small number of well-known Worker pairs, a shared HMAC secret works. For any scale beyond that, neither pattern fits.

ES256 JWTs fill this gap: asymmetric keys held by the sender, public keys held by the receiver, identity assigned by the receiver through its key registry.


Sender Worker(Account A)Cloudflare edgeadds CF-Worker headerAuthorization: Bearer <jwt>Receiver Worker(Account B)200 or 403Key registry(kid -> identity)lookup kidJTI Durable Object(replay check)check jtiPOST /api/data+ CF-Worker: example.com
StepWhat happensWhere
1Sender signs an ES256 JWT with claims: method, path, bodyHash, iss, aud, exp, jti, iat, plus optional srcZone/dstZoneSender Worker
2Sender attaches the JWT as Authorization: Bearer <jwt> and calls the receiverSender Worker
3Cloudflare edge adds CF-Worker: <zone> to the subrequestCloudflare edge
4Receiver decodes the JWT header, extracts kid, and looks up the key in its registryReceiver Worker
5Receiver verifies the ES256 signature against the registered public keyjose.jwtVerify()
6Receiver checks iss, aud, exp, maxTokenAgejose.jwtVerify() options
7Receiver runs JTI replay check against the Durable Object storeJTI DO
8Receiver resolves identity from the key registry entry (not from the JWT claims)RegisteredKey.identity
9Receiver checks the CF-Worker header matches the registered identity zoneRuntime check
10Receiver checks the destination zone (from request.url.hostname) matches dstZone claimRuntime check
11Receiver checks the request method matches the JWT method claimRuntime check
12Receiver checks the request path matches the JWT path claimRuntime check
13Receiver hashes the request body (SHA-256, base64url) and checks it matches bodyHash if presentcrypto.subtle.digest()

The receiver builds identity from three independent signals. Only one - the key registry - is load-bearing.

LayerSourceTrust levelSpoofable
Key registry (kid -> identity)Receiver’s KEY_REGISTRY env varReceiver-controlled - highestNo (needs private key)
CF-Worker headerCloudflare edge, added to Worker subrequestsCloudflare-attestedYes, by non-Worker clients
Destination hostnamerequest.url.hostname at runtimeRuntime-derivedNeeds DNS/routing attack

Key registry: the receiver holds a list of { kid, publicKeyPem, identity: { zone, account?, worker? } } entries. When it sees a JWT with kid: "sender-a", it finds that entry, verifies the signature against the stored public key, and reads the identity from the entry. The sender’s srcZone/srcAccount claims in the JWT are ignored. Identity is receiver-assigned, not self-asserted.

Unlike a shared-secret HMAC, the receiver here can revoke a sender by removing its registry entry, and the sender cannot assert a zone it does not own.

CF-Worker header: Cloudflare adds CF-Worker: <zone> to all Worker subrequests2. It is set by the edge, not by user code. However, Cloudflare does not document stripping it from non-Worker requests - a direct client could set this header and it would pass through. The equivalent trustworthy field (cf.worker.upstream_zone) exists only in the WAF/Rules Engine, not the Workers runtime API3.

In this system, CF-Worker is a defence-in-depth signal. The JWT signature + key registry is the real proof. A CF-Worker mismatch is rejected; an absent header is logged as “skip” rather than failure.

Destination hostname: the receiver derives its own zone from request.url.hostname at runtime, so a misconfigured receiverZone env var does not silently accept tokens meant for another hostname.


Each JWT carries a jti (JWT ID) claim - a unique token identifier4. The receiver stores seen JTIs and rejects any that appear a second time.

The library provides two backends:

StoreConsistencyStorageWhen to use
Durable Object (createDoJtiStore())Strong - single writer per DO instance, no replication lagDO storage, automatically expires entries after token TTLProduction. No replay can slip through during a write propagation window.
KV (createKvJtiStore())Eventual - KV writes are globally consistent within 60 seconds but reads can be staleKV namespace, TTL-based expiryNon-critical or budget-constrained paths where a short replay window is acceptable.

The DO store is the recommended default. A DO instance is a single-threaded actor: every JTI check+store is serialised, so two requests with the same JTI arriving at the same DO instance are linearised and only one succeeds.


AWS, GCP and Kubernetes platforms cryptographically attest a caller’s identity at the infrastructure layer because they control the runtime. Cloudflare’s Workers runtime does not expose an account ID or Worker-level identity certificate, so the application must supply its own.

SystemIdentity attested bySelf-assertionConsistency
This system (ES256 JWT + registry)Private key + receiver key registry + CF-Worker headerNo (registry mode)Strong (DO)
AWS IAM (STS)AWS platformNoStrong
GCP Workload IdentityExternal IdP + GCP STSNoStrong
SPIFFE/SPIREPlatform attestation (kernel, kubelet)NoStrong
Istio mTLSKubernetes service account + CANoStrong
OAuth client_credentialsAuth server + client secretNoStrong

Systems that do platform attestation have a structural advantage - the platform can prove who the caller is without the application holding a secret. On Cloudflare, the application must carry a secret (the private key), so key hygiene matters: short-lived tokens (60 s default), per-JWT request binding (method + path + body hash), and receiver-side revocation (remove the registry entry).

AttackImpactMitigated by
Private key compromiseFull impersonationShort-lived tokens (60 s), receiver-side revocation (remove key entry)
CF-Worker spoofingNone - JWT signature must pass firstSignature verification runs before CF-Worker check
Token replayNoneJTI stored in DO with TTL, strong consistency
Token reuse on different endpointNoneMethod + path + body hash bound in JWT
Receiver misconfigurationReduced - destination derived from hostnamerequest.url.hostname used at runtime

The receiver supports three strategies for resolving which key to verify against:

StrategyHow it worksWhen to use
Key registry (keys)kid in JWT header -> registry entry -> public key + identityRecommended. Identity is receiver-controlled.
Single key (publicKeyPem)One public key without kid. Identity from JWT claims, filtered by allowedSourceZones.Legacy single-sender. Sender self-asserts identity.
JWKS URL (jwksUrl)Fetches keys from an OIDC provider (Authentik, Keycloak). Identity from the OIDC token’s claims.Delegate identity to an external IdP.

The key registry is the recommended mode. It supports key rotation via publicKeyPemOld on each entry: the receiver tries both current and old keys during rotation, with zero downtime.


Need Worker-to-Worker auth?Both Workers in sameCloudflare account?Use service bindings(fetch binding, no auth needed)YesDestination orange-clouded(proxied)?NoUse mTLS cert bindings(mtls_certificate)No (DNS-only)More than 2-3 sendersor churn expected?YesShared HMAC secret(simple, static)NoES256 JWT + key registry(this system)YesES256 JWT + JWKS from IdPNeed external IdP?
ScenarioApproachEffort
Same account, no auth policy neededService bindingsNone
Cross-account, DNS-only (grey-clouded)mTLS cert bindingsLow
Cross-account, 2-3 static sendersShared HMAC secretLow
Cross-account, many senders or key rotationES256 JWT + key registry (this system)Medium
Cross-account, external identity providerES256 JWT + JWKS from IdPMedium-high

ClaimHow it was checkedEvidence
mTLS cert bindings return 520 on orange-clouded destinationsDocumentation. The binding type registers a client certificate that Cloudflare presents on the TLS handshake to the origin; on an orange-clouded zone the handshake terminates at Cloudflare’s edge, not the origin, so the binding does not apply.worker-mtls-jose README “Why” section (design-property claim cross-checked against CF docs)
CF-Worker header added automaticallyDocumented Cloudflare behaviour. The header is added to all Worker subrequests; a header transform rule example in the CF docs shows how to detect cross-zone subrequests using it.Cloudflare Rules examples
13-step verification pipelineCode review of lib/verify.ts in worker-mtls-joseworker-mtls-jose/lib/verify.ts verifyRequest() function
JTI Durable Object provides strong consistencyCode review. The DO-backed store uses state.storage.get() + state.storage.put() in the same fetch() handler - single-threaded DO execution linearises all JTI operations.worker-mtls-jose/lib/jti.ts JtiDurableObject class
24 E2E tests passRead from READMEworker-mtls-jose README “E2E tests” section
Key rotation with publicKeyPemOldCode review. In verifyWithRegistry(), the verifier tries both current and old keys when a publicKeyPemOld is present, allowing a new key to deploy before the old one is removed.worker-mtls-jose/lib/verify.ts lines 72-85
Request binding (method + path + body hash)Code review. The signRequest() function includes method, path, and optional bodyHash in JWT claims; the receiver verifies all three.worker-mtls-jose/lib/sign.ts and lib/verify.ts

  • Caching with Cloudflare Workers: covers cross-zone Worker fetch behaviour, including the cf caching-option gap this authentication layer sits below
  • Gatekeeper IAM Gateway: a deny-first IAM policy evaluator that gates cache purge and DNS API calls - complementary: IAM rules authorise WHAT, this system authenticates WHO
  • Cloudflare + Supabase architecture reference: the Workers-to-Supabase auth model (Hyperdrive, JWKS, RLS identity) that this system extends to Worker-to-Worker calls
  • Magic WAN interoperability: private-path connectivity for Worker backends, useful when the receiver Worker sits behind Magic WAN rather than a public hostname
  1. Cloudflare, “mTLS,” Cloudflare Docs. https://developers.cloudflare.com/workers/runtime-apis/bindings/mtls/ ↩ ↩2

  2. Cloudflare, “Add a request header for subrequests from other zones,” Cloudflare Docs. https://developers.cloudflare.com/rules/transform/examples/add-request-header-subrequest-other-zone/ ↩ ↩2

  3. Cloudflare, “Available fields and functions - Request fields,” Cloudflare Docs (cf.worker.upstream_zone). https://developers.cloudflare.com/ruleset-engine/rules-language/fields/#field-cf-worker-upstream_zone ↩

  4. M. Jones, J. Bradley, N. Sakimura, “JSON Web Token (JWT),” RFC 7519, IETF. https://datatracker.ietf.org/doc/html/rfc7519 ↩