Worker auth

Worker auth

Abstract

AXIS Worker auth is API-key based, not session cookies. Keys are created by admins (X-Admin-Token), validated via KV when bound, and used as Authorization: Bearer on the script library and (when gated) on /api/run.

Core helpers: worker/src/auth.ts. Key CRUD: worker/src/keys.ts.

Conceptual model

Rendering…

Interface surface

AuthContext

{ key: string; userId: string; tier: string }

userId is a truncated SHA-256 of the key (stable partition id).

extractBearer

1. Authorization: Bearer <token>
2. Else query ?key=

requireApiKey

Returns either { ok: true, ctx } or { ok: false, status, code, message }.

Fail-closed with durable storage (2.0.1+)

When D1 is active but API_KEYS KV is not bound, inventable shape-only keys would partition real script data by attacker-chosen tokens with no mint/revoke path. In that configuration:

1. Only explicit ALLOW_OPEN_KEYS=1 accepts any non-empty Bearer (local demos).
2. Otherwise respond 503 API_KEYS_REQUIRED — bind API_KEYS and mint via /api/keys.

/api/run auth gate

From worker/src/runtime.ts:

Always rate-limited (30/min) regardless of auth — see Runtime.

Admin keys API (/api/keys)

Tiers: free | hobby | pro | team | enterprise.

Without ADMIN_TOKEN set, create always fails (isAdmin false).

Do not leave ADMIN_TOKEN = "" in [vars]. That empty assignment is still a Worker binding, and Cloudflare error 10053 rejects wrangler secret put ADMIN_TOKEN (Binding name already in use). axis secret put ADMIN_TOKEN comments the stub, deploys to drop it, then sets the secret.

CLI:

axis setup kv                 # create + bind API_KEYS
axis secret put ADMIN_TOKEN   # comments empty [vars] stub if present
axis keys create --tier hobby # prompts, or --admin-token / AXIS_ADMIN_TOKEN
axis keys validate --key pn_…

Without KV on validate: accepts well-formed pn_[a-f0-9]{48} as hobby (dev).

ALLOW_OPEN_KEYS

wrangler.toml defaults local demos to "1":

accept any non-empty Bearer key for /api/scripts

Never leave open in production. Prefer bound API_KEYS + real admin-minted keys.

Internals

Key format

'pn_' + 24 random bytes as hex  // 48 hex chars

Invariants & edge cases

1. Admin token is a shared secret — rotate via wrangler secrets in production, not committed vars.
2. KV record shape — JSON { key, tier, createdAt } under key:${apiKey}.
3. No OAuth / cookies — PWA stores the key in plugin config (storage:cloud).
4. Stream DO unauthenticated — public market data only.

Worked examples

Create a key (admin)

curl -sS -X POST 'http://127.0.0.1:8787/api/keys?action=create' \
  -H "X-Admin-Token: $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"tier":"hobby"}'

Validate

curl -sS 'http://127.0.0.1:8787/api/keys?action=validate' \
  -H "Authorization: Bearer pn_…"

Failure modes

See also

• Data plane
• Bindings
• Runtime
• Security tests
• AXIS CLI — axis secret put · axis setup oauth