feat: configurable runtime-token header (server + SDK)

[josjeon]

TL;DR

The runtime-token JWT can now travel on a configurable header instead of always Authorization. Default is unchanged (Authorization), so existing deployments are unaffected. Set one env var on both the server and the SDK to move it to a dedicated header.

AGENT_CONTROL_RUNTIME_TOKEN_HEADER = X-Agent-Control-Runtime-Token

The problem

When Agent Control sits behind an API gateway, the gateway often puts its own identity JWT on Authorization. That overwrites our runtime token on the hot evaluation path, and the verifier rejects the request.

BEFORE  (collision on Authorization)

  SDK ──Authorization: Bearer <runtime-token>──▶ ┌─────────┐
                                                 │ Gateway │ overwrites Authorization
                                                 └────┬────┘ with its own identity JWT
                                                      │
                          Authorization: Bearer <gateway-jwt>
                                                      ▼
                                                ┌─────────┐
                                                │   AC    │ runtime token is gone → 401
                                                └─────────┘

AFTER  (two headers, no collision)

  SDK ──Authorization:                 (free for the gateway)──▶ ┌─────────┐
      └─X-Agent-Control-Runtime-Token: <runtime-token>─────────▶│ Gateway │ sets its own
                                                                 └────┬────┘ Authorization JWT
                          Authorization: Bearer <gateway-jwt>        │
                          X-Agent-Control-Runtime-Token: <token>─────┤ (passed through)
                                                                     ▼
                                                               ┌─────────┐
                                                               │   AC    │ reads runtime token
                                                               └─────────┘ from its own header → OK

The fix

One knob, wired on both sides:

Side	How to set it	Effect
Server	AGENT_CONTROL_RUNTIME_TOKEN_HEADER env	Verifier reads the runtime token from this header
SDK	same env, or runtime_token_header= param	Client sends the runtime token on this header

Rules for the header value:

• Authorization (default): Bearer prefix required — fully back-compatible.
• Dedicated header: raw token, Bearer prefix optional (nothing else competes for that header).
• Unset or whitespace-only env → falls back to Authorization (server and SDK behave identically). An explicit blank param on the SDK is a hard error.

Security: this only chooses which header the opaque token is read from. After extraction the token is still signature-verified, scope-checked, and target-bound (target_type + target_id) exactly as before — the header choice cannot bypass verification. A runtime token presented on Authorization is not accepted when the verifier is configured for a dedicated header (no silent fallback).

Single credential: in jwt mode the runtime token is the only credential on an evaluation request. The SDK suppresses X-API-Key when a runtime token is present, whether it rides Authorization or a dedicated header. The auto-fallback path (exchange unavailable, no token minted) and the token-exchange call itself still send X-API-Key, so nothing silently becomes unauthenticated.

What changed

Server

• auth_framework/providers/local_jwt.py — LocalJwtVerifyProvider gains a header_name param; _extract_bearer_token applies the Bearer rule above. DEFAULT_RUNTIME_TOKEN_HEADER is the single source of truth.
• auth_framework/config.py — new env resolved by _resolve_runtime_token_header().

SDK (sdks/python)

• client.py — AgentControlClient gains runtime_token_header; _merge_runtime_headers sends on the configured header; _format_runtime_token owns the Bearer-prefix rule; _AgentControlAuth suppresses X-API-Key when a runtime token is present.

Commits

1. feat(auth): make the runtime-token header configurable — server verifier + config + tests
2. feat(sdk): send the runtime token on the configurable header — Python SDK + tests

Tests

• Server — custom-header raw/Bearer acceptance, case-insensitive lookup, no-fallback-to-Authorization, whitespace/blank handling, config wiring; app-level E2E through /api/v1/evaluation proving a gateway JWT on Authorization and the runtime token on a dedicated header coexist.
• SDK — custom-header send (raw, no Bearer; Authorization and X-API-Key both absent), env override, defaults, blank/whitespace handling, custom-header auto-fallback keeping X-API-Key, and exchange auth in custom-header mode.

Test plan

• Server auth suites — 134 passed
• SDK suite — 38 passed
• ruff check + mypy clean on all changed files
• Reviewer: confirm the default (Authorization) path is unchanged for existing deployments
• lab0 E2E through the real gateway (tracked separately)

🤖 Generated with Claude Code