Provider connections and models
Two ways to authenticate an engine, the gateway providers behind them, and the model families served, with the credential never entering a sandbox.
An engine needs credentials to run. UseAgent stores them on the trusted backend and resolves them at turn time, so a sandbox never holds a reusable secret.
Two authentication methods
Managed account
A ChatGPT or Codex account connected with an OAuth device flow. The token bundle is stored encrypted and used from the trusted backend.
API key
A provider key stored write-only, encrypted with AES-256-GCM, resolved inside the signed provider gateway.
Connections belong to the signed-in user within the organization, not to the
organization as a whole. Every provider-connections route requires an
authenticated user and returns 403 user_required otherwise; the org-level dev
fallback alone is not enough. Reads return metadata for the current user’s
connections only.
The connection lifecycle is driven from Settings:
| Operation | Endpoint |
|---|---|
| List the current user’s connections | GET /api/provider-connections |
| Managed account OAuth | POST .../openai/chatgpt-oauth/start, GET .../status, POST .../cancel, POST .../revoke |
| Store or update a provider key | PUT .../:provider/api-key |
| Revoke a provider credential | POST .../:provider/revoke |
There is no POST or PUT on the collection root: creation and update happen
only through the per-provider key route and the OAuth subroutes.
Gateway providers and models
API-key engines are served through the provider gateway, which fronts three upstreams:
| Provider | Endpoint | Models |
|---|---|---|
| Anthropic | api.anthropic.com |
claude-* |
| OpenAI | api.openai.com |
gpt-* |
| OpenRouter | openrouter.ai/api |
Aggregated across providers |
OpenCode runs against its own native models. Which engines and models are
selectable in the UI is deployment configuration plus proven readiness, not a
per-organization setting: the ENABLED_ENGINES env only adds optional engines
on top of the base set, and GET /api/config filters further to engines whose
readiness is proven (auth mode established, provider health ready).
The Codex subscription relay
A managed Codex subscription does not put OAuth state in a sandbox. The Codex app-server and the ChatGPT OAuth stay on the trusted backend, and only the Codex exec-server runs inside the sandbox, reached over a one-use, run-bound relay. See Engines.
Connection reconcile
A provider-connection row heals from broker truth. A revoked row may only be reclaimed when the live account email differs from the revoked one, which proves a genuinely new login rather than a stale pre-logout snapshot.