feat: [Option A] configurable runtime-token header (server + SDK) [Need Discussion]

[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

Two options for resolving the collision

The collision can be fixed on either side of the boundary. This PR is Option A (agent-control side). A parallel spike sketches Option B (gateway side) for comparison (api-gateway !1351).

	Option A — agent-control side (this PR)	Option B — gateway side
Where the change lives	AO server + Python SDK	API Gateway AuthenticationFilter
Mechanism	Runtime token moves to a configurable header (e.g. X-Agent-Control-Runtime-Token); gateway Authorization is left alone	Gateway preserves the caller's Authorization on an opt-in, path-scoped allow-list
Gateway auth path	untouched	modified (guarded, default-off)
AO / SDK change	required	none
Blast radius	AO only	gateway — contained to configured paths, off by default
Needs platform + architecture/compliance sign-off	no	yes
Reference	this PR	api-gateway !1351

Option A keeps the gateway's auth path entirely out of scope — no shared-infrastructure change, no platform/compliance review — which is why it's the front-runner. Option B is captured separately so the "fix it in the gateway" path is a concrete artifact to compare against rather than a hypothetical.

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 — PENDING. Not yet run. This is the only end-to-end verification of the "gateway overwrites Authorization" premise; everything above is unit/integration scope. Tracked separately.

🤖 Generated with Claude Code

[abhinav-galileo]

Could we keep the configured request credential when the runtime token is sent on a dedicated header? In a two-hop setup, the outer credential authenticates the gateway while the runtime token authenticates Agent Control, so both are required on the evaluation request. Please update the custom-header test to assert that both headers are sent.

[abhinav-galileo]

Could we preserve the existing positional constructor order? Inserting runtime_token_header before runtime_token_cache changes how existing positional calls bind and can fail when the cache is treated as a header. Making the new option keyword-only after the existing parameters would avoid the compatibility break.

[abhinav-galileo]

Could we expose runtime_token_header through agent_control.init() as well? The high-level flow creates clients internally, so constructor-only configuration otherwise requires setting a process-wide environment variable.

[abhinav-galileo]

Small OSS wording suggestion: could we refer to this as an upstream gateway rather than an O11y gateway, to keep the committed test generic?