skip to content

Why does a Cloudflare Worker reach its KV namespace and R2 bucket through bindings on env rather than through an API token?

level: middleimportance: must knowfreq 58%

answer

  1. a permission and an API in one
  2. no credential in the code
  3. binding name versus resource id
  4. declared in the Wrangler file

basics

~20 s

A binding hands the Worker a ready-made object for one resource, such as env.RECEIPTS for an R2 bucket, with the permission built in. No token sits in code to leak, and no REST endpoint has to be called.

solid answer

~50 s

A binding is declared in the Wrangler file, for example `"r2_buckets": [{ "binding": "RECEIPTS", "bucket_name": "payment-receipts" }]`, and the runtime places an object with that resource's methods on `env`. Cloudflare describes it as a permission and an API in one piece: the Worker calls `env.RECEIPTS.put()` without holding any key, so nothing can leak through logs, a repository or an error report, and the grant covers that one bucket rather than whatever an account token allows. The REST API with an API token is meant for applications outside Workers; from inside a Worker, bindings perform better and carry fewer restrictions. The binding name is the code's handle and the resource id lives only in configuration, so pointing at another namespace or bucket is a config change, not a code change. In local development the same bindings connect to simulated resources by default.

code

json · 8 lines
json
{
  "kv_namespaces": [
    { "binding": "WEBHOOK_STATE", "id": "0f2ac74b498b48028cb68387c421e279" }
  ],
  "r2_buckets": [
    { "binding": "RECEIPTS", "bucket_name": "payment-receipts" }
  ]
}

go deeper

for a junior

Recall that a binding is declared in the Wrangler file and appears on env as an object, such as env.RECEIPTS for an R2 bucket.

for a middle

Explain the split between binding name and resource id, and why a binding needs no credential in code while a REST call needs a token.

for a senior

Argue from blast radius: a leaked token works anywhere with all its permissions, while a binding grants one resource to one Worker and cannot be copied out.

for a principal

Turn it into a team rule: Workers reach Cloudflare resources through bindings, and API tokens stay in CI and tooling with the narrowest permissions possible.

## What a binding is A **binding** is a named entry in a Worker's Wrangler configuration that attaches one resource, or one value, to the Worker. At run time it appears as a property of the `env` object passed to each handler. A binding has three parts: - a **binding name**, such as `WEBHOOK_STATE`, which becomes `env.WEBHOOK_STATE` in code; - a **type**, set by the configuration key it sits under (`kv_namespaces`, `r2_buckets`, `d1_databases`, `services`, `queues` and others); - a **resource identifier**, such as a KV namespace `id` or an R2 `bucket_name`, which tells Cloudflare what to attach. For a resource binding, `env.WEBHOOK_STATE` is an object with that product's methods (`get()` and `put()` for KV, `put()`, `get()` and `head()` for R2). Vars, secrets and Secrets Store secrets are bindings too; they carry values rather than resources. Wrangler prints the full list whenever it starts a dev session or deploys, under the heading "Your Worker has access to the following bindings", with each `env.NAME`, the resource it points at and its type. Reading that table is the quickest way to confirm which Cloudflare resources and values a Worker can reach through bindings, and review of a change to it is review of the Worker's access. ## The token alternative and what it costs A Worker could instead call Cloudflare's REST API for KV or R2 with an API token stored as a secret. Cloudflare's documentation steers Workers away from that, and the reasons are concrete: - **The credential exists in the Worker.** A token is a bearer credential: whoever copies it from a log line, an error report or a debugging session can use it from anywhere. With a binding the underlying credential is never exposed to the Worker's code, so it cannot be leaked. - **The grant is wider.** A token carries whatever permissions its creator gave it, often far more than one bucket. A binding grants exactly the resource it names to exactly this Worker. - **Each call is a network request** to an API built for applications outside Workers. From inside a Worker, bindings give better performance and fewer restrictions. - **Code must assemble URLs, account ids and authentication headers**, instead of calling `env.RECEIPTS.put(key, body)`. - **The credential needs looking after.** A token stored as a secret has to be replaced when it leaks or when its owner leaves; a binding has no value of its own to replace. ## Binding name versus resource id | Field | Example | Used by | |---|---|---| | `binding` | `RECEIPTS` | Worker code, as `env.RECEIPTS` | | `bucket_name` (R2) | `payment-receipts` | Cloudflare, to find the bucket | | `id` (KV) | `0f2ac74b498b48028cb68387c421e279` | Cloudflare, to find the namespace | The split has practical consequences: 1. Swapping the bucket or namespace behind a binding is a configuration change; the code keeps using the same name. 2. Renaming a binding is a code change, because every `env.RECEIPTS` reference must follow. 3. Two Workers can bind the same bucket under different names; the resource does not know what a Worker calls it. 4. Resource ids never need to appear in source code at all. ## Changing bindings safely When a deploy changes only a Worker's bindings and not its code, Cloudflare may reuse isolates already running that code. That makes a binding change fast, but anything derived from a binding and stored in global scope (a client built from a secret, say) can outlive the change. Read bindings from `env` inside the handler, or rebuild derived objects when the value changes. ## Local runs and types In local development, bindings connect to locally simulated KV namespaces, R2 buckets and other resources by default, and can be pointed at real resources with remote bindings; the local development material covers the details. In TypeScript, `wrangler types` turns the binding list into an `Env` interface, so `env.RECEIPTS` is typed as an `R2Bucket`. ## Where tokens still belong - A CI pipeline that runs `wrangler deploy` authenticates with an API token, because it acts on the account from outside any Worker. - Scripts and other systems that manage the account use tokens too. - If a Worker must call a Cloudflare API that has no binding, store that token as a secret and grant it only what the call needs.

  • Can two Workers bind the same R2 bucket under different binding names?
    Yes. The binding name is local to each Worker's configuration; both entries point at the same `bucket_name`, and each Worker's code uses its own name on `env`. That is also why swapping the bucket behind a binding is a configuration change while renaming the binding is a code change.
  • When is an API token still the right tool for a team building on Workers?
    Outside the runtime: a CI pipeline running `wrangler deploy`, and scripts or systems that manage the account. Inside a Worker, only for a Cloudflare API that has no binding, and then stored as a secret with the narrowest permissions the call needs.

  • Storing an account API token as a secret so the Worker can call KV over REST.
  • Believing a binding is an API token that Wrangler injects into env.
  • Renaming the binding when the team only wanted to point at another bucket.
  • Hard-coding the namespace id in Worker code instead of the Wrangler file.
  • Assuming bindings only work after deployment and cannot be used locally.