Authentication

Artifacts uses a different authentication path for each interface. Choose auth based on how your code reaches the repo.

Review Namespaces first, then use one namespace name consistently across each interface.

Compare auth methods

Interface	Authenticate with	Permissions or scopes	Use for
Workers binding	Configured `artifacts` binding	Wrangler auth is only for local Wrangler commands such as `dev` and `deploy`.	Worker code that calls `env.ARTIFACTS`
REST API	Cloudflare API token in `Authorization: Bearer ...`	Artifacts > Read for read routes and Artifacts > Edit for write routes.	Control-plane HTTP requests
Git protocol	Repo-scoped Artifacts token	`read` for clone, fetch, and pull. `write` for push.	Standard Git over HTTPS

Cloudflare API tokens authenticate control-plane access. Repo-scoped Artifacts tokens authenticate Git access.

Authenticate the Workers binding

The Workers binding uses the artifacts binding you configure in Wrangler. Your Worker code does not pass a token when it calls env.ARTIFACTS.

Add the binding in your Wrangler config:

wrangler.jsonc
wrangler.toml

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "artifacts-worker",
  "main": "src/index.ts",
  // Set this to today's date
  "compatibility_date": "2026-05-05",
  "artifacts": [
    {
      "binding": "ARTIFACTS",
      "namespace": "default"
    }
  ]
}

name = "artifacts-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-05-05"

[[artifacts]]
binding = "ARTIFACTS"
namespace = "default"

At runtime, deployed Workers use the configured binding directly. For local Wrangler commands such as wrangler dev, wrangler deploy, or wrangler types, authenticate Wrangler first. For local OAuth authentication, refer to wrangler login. For CI or headless environments, refer to Running Wrangler in CI/CD.

Authenticate the REST API

The REST API uses a Cloudflare API token in the Authorization header.

export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ARTIFACTS_NAMESPACE="default"
export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
export ARTIFACTS_BASE_URL="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts/namespaces/$ARTIFACTS_NAMESPACE"

Read repo metadata:

curl "$ARTIFACTS_BASE_URL/repos/starter-repo" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Create a repo:

curl --request POST "$ARTIFACTS_BASE_URL/repos" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "starter-repo"
  }'

Authenticate the Git protocol

Git uses repo-scoped Artifacts tokens, not Cloudflare API tokens. Mint these tokens from the Workers binding or the REST API, then use them with the repo remote URL.

Token scope	Allowed commands
`read`	`git clone`, `git fetch`, `git pull`
`write`	`git clone`, `git fetch`, `git pull`, `git push`

Use the exact repo remote value returned by the Workers binding or REST API:

export ARTIFACTS_REMOTE="<PASTE_REMOTE_FROM_CREATE_OR_GET_RESPONSE>"

Use a read token to clone:

git -c http.extraHeader="Authorization: Bearer <YOUR_READ_TOKEN>" clone "$ARTIFACTS_REMOTE" artifacts-clone

Use a write token to push:

git -c http.extraHeader="Authorization: Bearer <YOUR_WRITE_TOKEN>" push "$ARTIFACTS_REMOTE" HEAD:main

For more information on token handling and authenticated remotes, refer to Git protocol.