concepts
Modes: BYO & managed
Every request resolves to a mode — whose credential pays for the upstream call. The mode interacts with routing in exactly four combinations, one of which is rejected on purpose. The resolved mode is always visible on the x-understudy-mode response header.
The two modes
| mode | upstream credential | when |
|---|---|---|
byo | Your provider key, sent per request on x-understudy-upstream-key. Understudy never stores it. | You keep your Anthropic/OpenAI account and bills; the gateway adds capture and scoping. |
managed | Understudy's supply — pooled or dedicated credentials held server-side. | Catalog models, routed workloads, or passthrough through Understudy-managed provider credentials. |
The four routing × mode cases
| case | behavior |
|---|---|
| passthrough + managed | Forwarded to the provider your code called, paid by the managed credential configured for your org. No model rewrite. |
| passthrough + BYO | Forwarded to the provider your code called with your provider key. No model rewrite. The gateway is a pure proxy with capture. |
| routed + managed | The workload's configured model route applies: the request is rewritten to the routed model and served from Understudy supply. |
| routed + BYO | Rejected with 400. A request can't simultaneously say "use my provider key" and be rewritten to a model that key can't serve — the ambiguity is refused rather than guessed at. |
Provider coverage
Per-request BYO accepts Anthropic and OpenAI keys — the two API shapes the gateway speaks natively. Models from other providers are available in managed mode through the model catalog. Stored provider keys (registering a key once instead of sending it per request) is designed but not yet shipped; when it lands it will widen BYO coverage beyond the two native providers.